Overview

Relevant source files

• README.md
• app/meson.build
• app/src/main.c
• app/src/scrcpy.h
• doc/build.md
• doc/linux.md
• doc/macos.md
• doc/windows.md
• install_release.sh
• meson_options.txt
• server/meson.build
• server/scripts/build-wrapper.sh

This document provides a high-level introduction to scrcpy, its architecture, and how the major components interact. It is intended for developers who want to understand the system structure before diving into specific subsystems.

For installation instructions, see Installation & Setup. For command-line usage, see Command-Line Interface. For detailed architecture and communication protocols, see System Architecture.

Purpose and Scope

scrcpy (pronounced "screen copy") is a screen mirroring and control application that displays and controls Android devices from desktop computers. It operates as a client-server system where a lightweight Java server runs on the Android device and a native client application runs on the desktop (Linux, Windows, or macOS).

Key characteristics:

• No device modification required: Does not require root access or a pre-installed Android application [README.md:12-15].
• High performance: 30-120 fps with low latency (35-70ms) [README.md:26-28].
• Cross-platform: Works on Linux, Windows, and macOS [README.md:15-15].
• Minimal footprint: Server (scrcpy-server) is deployed temporarily via ADB and leaves no permanent installation [README.md:30-30].
• Multiple features: Screen mirroring, audio forwarding (Android 11+), input control, recording, camera access, and V4L2 virtual camera [README.md:37-47].

Sources: README.md6-61

System Architecture

scrcpy consists of two main components that communicate over network sockets established via ADB:

Architecture: Desktop client (C) and Android server (Java)

The architecture follows a clear separation:

• Desktop Client: Manages display, decoding, user input, and recording.
• Android Server: Manages capture, encoding, and control execution.
• Communication Layer: ADB establishes TCP tunnels; independent sockets carry video, audio, and control data.

Sources: app/src/main.c27-126 app/src/scrcpy.h19-20 app/meson.build1-69

Client-Server Lifecycle

The system follows a well-defined initialization and runtime sequence:

Initialization Sequence: From user invocation to active mirroring

Key phases:

1. Argument Parsing: main.c calls scrcpy_parse_args() to process command-line options into struct scrcpy_options [app/src/main.c:54-57].
2. Server Deployment: The client handles server binary deployment and ADB tunnel setup via server.c [app/meson.build:35-35].
3. Server Execution: The server is launched via app_process on the device, typically using Server.java as the entry point.
4. Event Loop: The client enters the main loop in scrcpy() to process media and inputs [app/src/scrcpy.h:19-20].

Sources: app/src/main.c39-107 app/src/scrcpy.h8-20 install_release.sh1-22

Build and Deployment Model

scrcpy uses separate build systems for client and server:

Build and Deployment: Client builds natively; server builds to DEX

Client Build:

• Build system: Meson + Ninja [doc/build.md:227-229].
• Dependencies: FFmpeg, SDL3 (>= 3.2.0), libusb [app/meson.build:125-131].
• Platform: Supports Linux, Windows (MinGW cross-compile), and macOS [doc/build.md:45-183].

Server Build:

• Build system: Gradle or manual shell script [doc/build.md:208-251].
• Output: A DEX-containing JAR file (scrcpy-server) [install_release.sh:9-16].

Simplified Installation: The install_release.sh script automates installation on Linux by downloading a prebuilt server and building the client [install_release.sh:1-22].

Sources: doc/build.md1-270 install_release.sh1-22 app/meson.build1-198

Related Documentation

For more detailed information on specific subsystems:

• Architecture Details: System Architecture — communication protocols, threading model, and packet formats.
• Installation: Installation & Setup — detailed platform-specific setup and prerequisites.
• CLI Usage: Command-Line Interface — full documentation of available flags and parameters.