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/, andrelease/: 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 underserver/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 byaudio/,video/,control/,display/,device/,model/,util/, andwrappers/. - Build/release is intentionally dual-stack: native/client build configuration is rooted in
meson.buildandapp/meson.build, while Android server build configuration is rooted in build.gradle, settings.gradle, and server/build.gradle.
5. Routing table
-
app/…/main.c -> docs/client-application-entry-and-options.md
-
app/…/cli.c, app/…/cli.h -> docs/client-application-entry-and-options.md
-
app/…/options.c, app/…/options.h -> docs/client-application-entry-and-options.md
-
app/…/scrcpy.c, app/…/scrcpy.h -> docs/client-application-entry-and-options.md
-
app/…/events.c, app/…/events.h, app/…/sdl_hints.c, app/…/sdl_hints.h -> docs/client-application-entry-and-options.md
-
app/…/version.c, app/…/version.h, app/…/icon.c, app/…/icon.h, app/…/common.h -> docs/client-application-entry-and-options.md
-
app/scrcpy.1,app/meson.build-> docs/client-application-entry-and-options.md -
any CLI option, startup lifecycle, SDL event loop, or top-level client behavior change -> docs/client-application-entry-and-options.md
-
app/src/adb/**-> docs/client-server-bootstrap-and-adb-transport.md -
app/…/server.c, app/…/server.h -> docs/client-server-bootstrap-and-adb-transport.md
-
app/…/receiver.c, app/…/receiver.h -> docs/client-server-bootstrap-and-adb-transport.md
-
app/…/disconnect.c, app/…/disconnect.h -> docs/client-server-bootstrap-and-adb-transport.md
-
app/…/net.c, app/…/net.h, app/…/net_intr.c, app/…/net_intr.h -> docs/client-server-bootstrap-and-adb-transport.md
-
app/…/process.c, app/…/process.h, app/…/process_intr.c, app/…/process_intr.h, app/…/command.c, app/…/command.h -> docs/client-server-bootstrap-and-adb-transport.md
-
any device selection, ADB tunnel, server launch, receiver socket, or disconnect-flow change -> docs/client-server-bootstrap-and-adb-transport.md
-
app/…/demuxer.c, app/…/demuxer.h -> docs/client-video-decoding-rendering.md
-
app/…/decoder.c, app/…/decoder.h -> docs/client-video-decoding-rendering.md
-
app/…/packet_merger.c, app/…/packet_merger.h -> docs/client-video-decoding-rendering.md
-
app/…/video_regulator.c, app/…/video_regulator.h -> docs/client-video-decoding-rendering.md
-
app/…/frame_buffer.c, app/…/frame_buffer.h -> docs/client-video-decoding-rendering.md
-
app/…/screen.c, app/…/screen.h -> docs/client-video-decoding-rendering.md
-
app/…/fps_counter.c, app/…/fps_counter.h -> docs/client-video-decoding-rendering.md
-
app/…/egl.c, app/…/egl.h, app/…/opengl.c, app/…/opengl.h, app/…/texture.c, app/…/texture.h -> docs/client-video-decoding-rendering.md
-
app/…/hwdec.c, app/…/hwdec.h,
app/src/interop/**, app/…/v4l2_sink.c, app/…/v4l2_sink.h, app/…/vaapi_shim.c -> docs/client-video-decoding-rendering.md -
any client-side video stream, decode, render, frame timing, hardware interop, or video sink change -> docs/client-video-decoding-rendering.md
-
app/…/audio_player.c, app/…/audio_player.h -> docs/client-audio-playback-and-regulation.md
-
app/…/audio_regulator.c, app/…/audio_regulator.h -> docs/client-audio-playback-and-regulation.md
-
app/…/audiobuf.c, app/…/audiobuf.h -> docs/client-audio-playback-and-regulation.md
-
any client-side audio playback, audio buffering, or audio drift regulation change -> docs/client-audio-playback-and-regulation.md
-
app/…/controller.c, app/…/controller.h -> docs/client-control-input-and-hid.md
-
app/…/control_msg.c, app/…/control_msg.h -> docs/client-control-input-and-hid.md
-
app/…/device_msg.c, app/…/device_msg.h -> docs/client-control-input-and-hid.md
-
app/…/input_manager.c, app/…/input_manager.h, app/…/input_events.h, app/…/coords.h, app/…/shortcut_mod.h -> docs/client-control-input-and-hid.md
-
app/…/keyboard_sdk.c, app/…/keyboard_sdk.h, app/…/mouse_sdk.c, app/…/mouse_sdk.h, app/…/mouse_capture.c, app/…/mouse_capture.h -> docs/client-control-input-and-hid.md
-
app/src/android/**,app/src/hid/**,app/src/uhid/**,app/src/usb/**-> docs/client-control-input-and-hid.md -
any client input mapping, control-message serialization, HID/UHID/AOA backend, or device-message handling change -> docs/client-control-input-and-hid.md
-
app/src/util/**-> docs/client-platform-utilities-and-traits.md -
app/src/sys/**-> docs/client-platform-utilities-and-traits.md -
app/src/trait/**-> docs/client-platform-utilities-and-traits.md -
app/…/clock.c, app/…/clock.h, app/…/compat.c, app/…/compat.h -> docs/client-platform-utilities-and-traits.md
-
any reusable native utility, platform abstraction, collection, threading/synchronization, or producer/consumer trait change -> docs/client-platform-utilities-and-traits.md
-
app/…/recorder.c, app/…/recorder.h -> docs/client-recording-file-push-and-assets.md
-
app/…/file_pusher.c, app/…/file_pusher.h -> docs/client-recording-file-push-and-assets.md
-
app/data/**,app/scrcpy-windows.manifest,app/scrcpy-windows.rc-> docs/client-recording-file-push-and-assets.md -
any client recording, file push, desktop integration asset, icon, completion, or Windows resource change -> docs/client-recording-file-push-and-assets.md
-
server/…/Server.java -> docs/server-runtime-connection-and-foundations.md
-
server/…/Options.java -> docs/server-runtime-connection-and-foundations.md
-
server/…/AsyncProcessor.java, server/…/CleanUp.java, server/…/Workarounds.java, server/…/FakeContext.java, server/…/AndroidVersions.java -> docs/server-runtime-connection-and-foundations.md
-
server/src/main/java/com/genymobile/scrcpy/device/**-> docs/server-runtime-connection-and-foundations.md -
server/src/main/java/com/genymobile/scrcpy/model/**-> docs/server-runtime-connection-and-foundations.md -
server/src/main/java/com/genymobile/scrcpy/util/**-> docs/server-runtime-connection-and-foundations.md -
server/src/main/java/com/genymobile/scrcpy/wrappers/**-> docs/server-runtime-connection-and-foundations.md -
server/src/main/java/android/**,server/src/main/aidl/**, server/…/AndroidManifest.xml -> docs/server-runtime-connection-and-foundations.md -
any Android server startup, option parsing, desktop connection, wrapper, model, or utility foundation change -> docs/server-runtime-connection-and-foundations.md
-
server/src/main/java/com/genymobile/scrcpy/video/**-> docs/server-video-capture-encoding-and-display.md -
server/src/main/java/com/genymobile/scrcpy/display/**-> docs/server-video-capture-encoding-and-display.md -
server/src/main/java/com/genymobile/scrcpy/opengl/**-> docs/server-video-capture-encoding-and-display.md -
any Android-side video capture, display tracking, camera/screen source, OpenGL filter, virtual display, surface encoding, or video codec constraint change -> docs/server-video-capture-encoding-and-display.md
-
server/src/main/java/com/genymobile/scrcpy/audio/**-> docs/server-audio-capture-encoding.md -
any Android-side audio capture, playback/direct source, AudioRecord reader, audio codec/config, raw recording, or audio stream failure-mode change -> docs/server-audio-capture-encoding.md
-
server/src/main/java/com/genymobile/scrcpy/control/**-> docs/server-control-protocol-and-device-actions.md -
server/…/Device.java -> docs/server-control-protocol-and-device-actions.md
-
any Android-side control protocol, input injection, pointer/key mapping, UHID manager, clipboard/device action, or device-message response change -> docs/server-control-protocol-and-device-actions.md
-
meson.build, meson_options.txt,app/meson.build-> docs/build-test-release-and-packaging.md -
build.gradle, settings.gradle,
gradle.properties,gradlew,gradlew.bat,gradle/**-> docs/build-test-release-and-packaging.md -
config/**-> docs/build-test-release-and-packaging.md -
app/deps/**-> docs/build-test-release-and-packaging.md -
app/tests/**-> docs/build-test-release-and-packaging.md -
server/build.gradle,
server/meson.build, server/build_without_gradle.sh,server/proguard-rules.pro,server/scripts/**,server/src/test/**-> docs/build-test-release-and-packaging.md -
release/**, cross_win32.txt, cross_win64.txt,bump_version, install_release.sh,run-> docs/build-test-release-and-packaging.md -
any build, test, dependency bootstrap, packaging, cross-build, release, Gradle, Meson, or CI-like script change -> docs/build-test-release-and-packaging.md