scrcpy Administrator & Developer Guide

scrcpy (screen copy) is a high-performance client-server application that displays and controls Android devices from a desktop computer. The client is a native C application rendering through SDL2 and FFmpeg; the server is an Android Java application injected onto the device via adb. All communication flows over adb connections (USB or TCP/IP), requiring no root access and no app installation on the device.

This guide covers architecture, build system, configuration, deployment, security considerations, and developer internals for scrcpy v3.3.4 (commit 247a37d).

Table of Contents

• Architecture Overview
• System Requirements
• Configuration Reference
• Deployment & Scaling
• Operations
• Performance Tuning
• Security
• Developer Internals
• Integration Points

Architecture Overview

scrcpy operates as a two-component system: a host-side C client and a device-side Java server. The client pushes the server JAR to the device, launches it via adb shell, and establishes socket connections for video, audio, and control streams.

┌─────────────────────────────────────────────────────────────────┐
│                        HOST (Desktop)                           │
│                                                                 │
│  main.c ──► cli.c (parse args) ──► scrcpy.c (orchestration)    │
│                                        │                        │
│            ┌───────────────────────────┼──────────────────┐     │
│            │                          │                   │     │
│       server.c               demuxer.c (x2)        controller.c │
│    (push JAR, launch,     (video + audio)        (control msgs) │
│     establish sockets)         │                       │        │
│            │              decoder.c              control_msg.c   │
│            │                  │                       │         │
│            │         ┌───────┴────────┐               │        │
│            │         │                │               │        │
│            │    display.c /      recorder.c           │        │
│            │    screen.c (SDL)   (FFmpeg mux)         │        │
│            │         │                                │        │
│            │    audio_player.c                        │        │
│            │    (SDL audio)                           │        │
│            │                                          │        │
│            │    ┌──────────────────────┐               │        │
│            │    │  HID subsystem       │               │        │
│            │    │  hid/ (kb,mouse,pad) │               │        │
│            │    │  uhid/ (Linux UHID)  │               │        │
│            │    │  usb/ (AOAv2)        │               │        │
│            │    └──────────────────────┘               │        │
│            │                                          │        │
│            │    v4l2_sink.c (Linux)                    │        │
│            │    file_pusher.c (drag & drop)            │        │
└────────────┼──────────────────────────────────────────┼────────┘
             │              ADB (USB / TCP)              │
             │         ┌────────────────────┐            │
             ▼         ▼                    ▼            ▼
┌─────────────────────────────────────────────────────────────────┐
│                      DEVICE (Android)                           │
│                                                                 │
│  /data/local/tmp/scrcpy-server.jar                              │
│                                                                 │
│  Server.java (entry point)                                      │
│       │                                                         │
│       ├── Options.java (parse server-side options)               │
│       │                                                         │
│       ├── video/                                                │
│       │    ScreenCapture / CameraCapture / NewDisplayCapture    │
│       │    └── SurfaceEncoder ──► Streamer ──► socket           │
│       │                                                         │
│       ├── audio/                                                │
│       │    AudioDirectCapture / AudioPlaybackCapture             │
│       │    └── AudioEncoder / AudioRawRecorder ──► socket       │
│       │                                                         │
│       ├── control/                                              │
│       │    ControlMessageReader ──► Controller                  │
│       │    └── injects via InputManager, ClipboardManager, etc. │
│       │                                                         │
│       └── wrappers/ (hidden Android API access via reflection)  │
│            ActivityManager, ClipboardManager, DisplayControl,   │
│            DisplayManager, InputManager, PowerManager,          │
│            ServiceManager, StatusBarManager, SurfaceControl,    │
│            WindowManager, ContentProvider                       │
└─────────────────────────────────────────────────────────────────┘

Connection establishment

1. The client pushes scrcpy-server.jar to /data/local/tmp/scrcpy-server.jar on the device via adb push.
2. The client starts the server via adb shell with appropriate arguments.
3. By default, the client uses adb reverse to make the device connect back to the host (the client listens, the server connects). The --force-adb-forward flag reverses this so the client connects to a forwarded port instead.
4. The socket name prefix used is scrcpy_.
5. Separate socket connections are established for video, audio, and control streams.

Data flow summary

Note

scrcpy does not install anything on the device. The server JAR is pushed to a temporary location and executed via adb shell. No permanent modifications are made.

System Requirements

Host requirements

Device requirements

Build-time requirements

Important

The server targets compileSdk: 36, minSdk: 21, targetSdk: 36. The server has zero runtime dependencies beyond the Android SDK itself; junit:junit:4.13.2 is used for tests only.

Configuration Reference

CLI options (complete list)

All options are passed to the scrcpy client binary. The client translates them into server arguments where applicable.

Video options

Audio options

Recording options

Input options

Connection options

Display options

Device control options

Miscellaneous options

Environment variables

Exit codes

Default ADB port

The default ADB port for TCP/IP connections is 5555.

Deployment & Scaling

Building from source

Building the server

The server is an Android Java application built with Gradle:

# Standard Gradle build
cd server
./gradlew assembleRelease

The server can also be built without Gradle using the Android SDK directly:

cd server
./build_without_gradle.sh

Note

The server build produces a JAR file. ProGuard rules are defined in server/proguard-rules.pro for release builds.

Building the client

The client uses Meson and Ninja:

# Configure
meson setup build --buildtype=release

# Build
ninja -C build

# Install
sudo ninja -C build install

Build options are defined in meson_options.txt and can be set during configuration:

meson setup build --buildtype=release -Doption_name=value

Using install_release.sh

The install_release.sh script automates the full process: downloads a prebuilt server binary, builds the client with Meson and Ninja, and installs everything:

./install_release.sh

Cross-compilation

Cross-compilation configurations are provided for Windows targets:

Usage:

meson setup build-win64 --cross-file cross_win64.txt --buildtype=release
ninja -C build-win64

Warning

Cross-compilation requires the appropriate cross-compiler toolchain (e.g., MinGW-w64) and cross-compiled versions of all dependencies (SDL2, FFmpeg, libusb).

Packaging

Linux desktop integration

The app/data/ directory contains standard Linux desktop integration files:

• scrcpy.desktop — standard desktop entry
• scrcpy-console.desktop — desktop entry that keeps terminal open
• icon.png, icon.svg, icon.ico — application icons in multiple formats
• bash-completion/scrcpy — Bash tab completion
• zsh-completion/_scrcpy — Zsh tab completion

Windows packaging

• scrcpy-windows.manifest — Windows application manifest
• scrcpy-windows.rc — Windows resource file (icon, version info)
• open_a_terminal_here.bat — helper batch file
• scrcpy-console.bat — launch with console window
• scrcpy-noconsole.vbs — launch without console window

Man page

A man page is provided at app/scrcpy.1 for Unix-like systems.

Server deployment on device

The server JAR is pushed to /data/local/tmp/scrcpy-server.jar on the device. On the host, the client looks for the server binary at:

1. The path specified by SCRCPY_SERVER_PATH environment variable
2. PREFIX/share/scrcpy/scrcpy-server (standard install location)

Operations

Running scrcpy

Basic usage

# Mirror default device over USB
scrcpy

# Mirror specific device
scrcpy -s DEVICE_SERIAL

# Mirror over TCP/IP
scrcpy --tcpip=192.168.1.100:5555

# Record while mirroring
scrcpy --record=session.mp4

# Mirror without audio
scrcpy --no-audio

# Mirror-only, no control
scrcpy --no-control

Display modes

# Fullscreen
scrcpy --fullscreen

# Always on top, borderless
scrcpy --always-on-top --window-borderless

# No display window (recording only)
scrcpy --no-window --record=capture.mp4

# Limit resolution
scrcpy --max-size=1024

# Mirror secondary display
scrcpy --display-id=1

Camera mirroring

# List available cameras
scrcpy --list-cameras

# Mirror front camera
scrcpy --video-source=camera --camera-facing=front

# Specific camera at specific size
scrcpy --video-source=camera --camera-id=0 --camera-size=1920x1080

Monitoring

FPS counter

scrcpy includes a built-in FPS counter (fps_counter.c) that can be enabled to log frame rates during a session. Verbosity level debug or lower will show frame timing information.

scrcpy --verbosity=debug

Log verbosity levels

Updating

scrcpy is a single-version deployment: the client and server must match. When updating:

1. Build or download the new client binary.
2. Ensure the matching server JAR is available at the expected path.
3. The old server on the device is overwritten on each connection (pushed fresh every time).

Caution

The client and server versions must be identical. A version mismatch will cause connection failures or undefined behavior.

File transfer

Drag and drop files onto the scrcpy window to push them to the device:

• Regular files are pushed to the directory specified by --push-target (default: /sdcard/Download/).
• APK files are automatically installed via adb install.

This is handled by file_pusher.c, which uses adb push under the hood.

Performance Tuning

Video encoding

Codec selection

Bit rate tuning

The default video bit rate is 8M (8 Mbps). Adjust based on use case:

# Low bandwidth / low latency
scrcpy --video-bit-rate=2M

# High quality recording
scrcpy --video-bit-rate=16M

Resolution limiting

# Limit to 1024px on the longest dimension
scrcpy --max-size=1024

# Cap framerate
scrcpy --max-fps=30

Tip

Reducing --max-size and --max-fps significantly decreases encoding load on the device and bandwidth usage, improving latency on slower connections.

Audio buffering

The audio pipeline uses a regulator (audio_regulator.c) that compensates for jitter using libswresample-based sample rate adjustment. When underflow occurs, silence is inserted to prevent audio glitches.

# Minimize audio latency (may cause glitches on poor connections)
scrcpy --audio-buffer=20 --audio-output-buffer=2

# Maximize audio stability
scrcpy --audio-buffer=200 --audio-output-buffer=20

Video buffering

The delay buffer (delay_buffer.c) holds frames to smooth out jitter. The frame buffer (frame_buffer.c) is a thread-safe single-frame buffer that always holds the latest decoded frame, dropping older frames when the display cannot keep up.

# Add 50ms video buffer for unstable connections
scrcpy --video-buffer=50

Codec options

Pass encoder-specific options directly to the device encoder:

# Set H.264 profile and level
scrcpy --video-codec-options=profile=1,level=2048

Encoder selection

List and select specific hardware/software encoders:

# List available encoders
scrcpy --list-encoders

# Force specific encoder
scrcpy --video-encoder=OMX.qcom.video.encoder.avc

Note

The packet merger (packet_merger.c) reassembles codec packets that may be split across multiple reads. This is transparent to the user but is relevant when debugging encoding issues.

Screen-off mode performance

Using --turn-screen-off / -S disables the device display, which can affect encoding performance on some devices (see GitHub issue #3376). If you observe performance degradation, test without this flag.

Security

Hidden Android API access

The server accesses non-public Android APIs via Java reflection through the wrappers/ package. This is the mechanism that allows scrcpy to function without root and without installing an APK.

Wrapped system services

Warning

These wrappers use reflection to access hidden (@hide) Android APIs. These APIs are not part of the public Android SDK and may change or be removed in any Android version. The server targets compileSdk: 36 but must handle API differences across Android versions (API 21+).

Network security

ADB connection model

scrcpy communicates exclusively over adb. There is no independent network protocol.

• USB mode: All traffic flows over the USB cable. No network exposure.
• TCP/IP mode (adb tcpip / --tcpip): ADB listens on port 5555 (default) on the device's network interface. This is an ADB-level concern, not scrcpy-specific.

Caution

When using ADB over TCP/IP, the ADB connection is unencrypted and unauthenticated on the network. Anyone on the same network can connect to the device. Use TCP/IP mode only on trusted networks. Consider using a VPN or SSH tunnel for remote connections.

Socket communication

• The client and server communicate via Unix domain sockets tunneled through adb (using adb reverse or adb forward).
• Socket name prefix: scrcpy_
• No TLS or encryption is applied at the scrcpy level; security relies on the adb transport layer.

Permissions model

scrcpy requires only that USB debugging be enabled on the device. It does not require:

• Root access
• Device unlock (though initial ADB authorization requires user approval on the device)
• Any installed APK

The server runs as the shell user, which has elevated privileges compared to normal apps (this is what enables input injection, screen capture, and clipboard access without root).

Data handling

• No data persistence on device: The server JAR at /data/local/tmp/scrcpy-server.jar is the only file written to the device. It is overwritten on each connection.
• Clipboard sync: When clipboard sync is enabled (default), clipboard content is transmitted between host and device. Use --no-control to disable all device control including clipboard sync.
• File push: Files dragged onto the window are pushed via adb push to the push target directory.

Developer Internals

Repository structure

scrcpy/
├── app/
│   ├── meson.build                    # Client build definition
│   ├── scrcpy.1                       # Man page
│   ├── scrcpy-windows.manifest        # Windows manifest
│   ├── scrcpy-windows.rc              # Windows resource file
│   ├── data/
│   │   ├── icon.ico, icon.png, icon.svg   # App icons
│   │   ├── scrcpy.desktop                 # Linux desktop entry
│   │   ├── scrcpy-console.desktop         # Console desktop entry
│   │   ├── open_a_terminal_here.bat       # Windows helper
│   │   ├── scrcpy-console.bat             # Windows console launcher
│   │   ├── scrcpy-noconsole.vbs           # Windows no-console launcher
│   │   ├── bash-completion/scrcpy         # Bash completions
│   │   └── zsh-completion/_scrcpy         # Zsh completions
│   ├── src/                           # Client C source (67 files)
│   └── tests/                         # Client unit tests (11 files)
├── server/
│   ├── build.gradle                   # Server Gradle build
│   ├── build_without_gradle.sh        # Build without Gradle
│   ├── proguard-rules.pro             # ProGuard config
│   ├── meson.build                    # Server Meson integration
│   ├── scripts/build-wrapper.sh       # Build wrapper
│   └── src/
│       ├── main/
│       │   ├── AndroidManifest.xml
│       │   ├── aidl/                  # AIDL interfaces
│       │   └── java/com/genymobile/scrcpy/
│       │       ├── Server.java        # Entry point
│       │       ├── Options.java       # Server options
│       │       ├── audio/             # Audio capture & encoding
│       │       ├── control/           # Control message handling
│       │       ├── device/            # Device interaction
│       │       ├── opengl/            # OpenGL support
│       │       ├── util/              # Utilities
│       │       ├── video/             # Video capture & encoding
│       │       └── wrappers/          # Hidden API wrappers
│       └── test/                      # Server unit tests
├── config/
│   ├── android-checkstyle.gradle      # Checkstyle Gradle integration
│   └── checkstyle/checkstyle.xml      # Checkstyle rules
├── doc/                               # 18 topic-specific docs
├── gradle/wrapper/                    # Gradle wrapper
├── meson.build                        # Root Meson build
├── meson_options.txt                  # Client build options
├── build.gradle                       # Root Gradle build
├── cross_win32.txt                    # Win32 cross-compilation
├── cross_win64.txt                    # Win64 cross-compilation
└── install_release.sh                 # Automated install script

Module reference (client)

Core orchestration

Server management

Video pipeline

Audio pipeline

Input and control

Recording and output

Utilities

Trait system (interface pattern)

scrcpy implements a trait-based interface pattern in C using function pointers in structs. This enables polymorphic composition of pipeline stages.

Frame traits

Packet traits

Input traits

This system allows components to be composed flexibly. For example, a demuxer (packet source) can feed packets to both a decoder and a recorder simultaneously. A decoder (frame source) can feed frames to both a display and a V4L2 sink.

Demuxer (packet_source)
  ├──► Decoder (packet_sink + frame_source)
  │       ├──► Display (frame_sink)
  │       └──► V4L2 Sink (frame_sink)
  └──► Recorder (packet_sink)

Server module reference

AIDL interfaces

• IOnPrimaryClipChangedListener.aidl -- clipboard change notifications
• IDisplayWindowListener.aidl -- display window events

Code style and quality

• Server code style: Enforced via Checkstyle (config/checkstyle/checkstyle.xml), integrated through config/android-checkstyle.gradle.
• Client code style: C99 standard, consistent naming conventions (sc_ prefix for scrcpy types).
• ProGuard: Release server builds use ProGuard rules from server/proguard-rules.pro.

Testing

Client tests

Located in app/tests/, 11 test files:

Running client tests:

meson setup build
ninja -C build
meson test -C build

Server tests

Located in server/src/test/:

Running server tests:

cd server
./gradlew test

Build system details

Meson build (client)

The root meson.build defines the overall project. app/meson.build specifies the client target with all source files, dependencies, and build options.

Key Meson dependencies resolved via pkg-config:

• sdl2
• libavcodec, libavformat, libavutil, libswresample
• libusb-1.0 (optional)

Build options are defined in meson_options.txt.

Gradle build (server)

• Android Gradle Plugin: 8.13.0
• compileSdk: 36
• minSdk: 21
• targetSdk: 36
• Version: 3.3.4
• Test dependency: junit:junit:4.13.2

Tip

The server can be built without Gradle using server/build_without_gradle.sh, which invokes the Android SDK tools directly. This is useful in CI environments or when Gradle is not available.

Integration Points

V4L2 sink (Linux only)

scrcpy can output video to a V4L2 loopback device, making the Android screen appear as a virtual webcam:

# Load v4l2loopback kernel module
sudo modprobe v4l2loopback

# Stream to V4L2 device
scrcpy --v4l2-sink=/dev/video2

# With buffering
scrcpy --v4l2-sink=/dev/video2 --v4l2-buffer=50

The V4L2 sink (v4l2_sink.c) implements the sc_frame_sink trait, receiving decoded frames from the decoder and writing them to the V4L2 device. It can operate alongside the normal display window, or with --no-window for headless streaming.

# Headless V4L2 streaming (no display window)
scrcpy --v4l2-sink=/dev/video2 --no-window

# V4L2 + recording simultaneously
scrcpy --v4l2-sink=/dev/video2 --record=capture.mp4

OTG mode

OTG mode (usb/scrcpy_otg.c) provides direct USB HID input without any mirroring or ADB connection. The host sends keyboard, mouse, and gamepad input directly over USB using the AOAv2 (Android Open Accessory v2) protocol.

# OTG mode with keyboard and mouse
scrcpy --otg

# OTG mode with specific device
scrcpy --otg -s DEVICE_SERIAL

Important

OTG mode requires libusb and only works on Linux. It bypasses ADB entirely -- the device appears as a USB accessory. No video/audio mirroring occurs in OTG mode.

HID input modes

scrcpy supports three input injection methods, selectable independently for keyboard, mouse, and gamepad:

# UHID keyboard + mouse
scrcpy --keyboard=uhid --mouse=uhid

# AOA keyboard + mouse
scrcpy --keyboard=aoa --mouse=aoa

# Mixed: UHID keyboard, SDK mouse
scrcpy --keyboard=uhid --mouse=sdk

Virtual display

scrcpy can create a new virtual display on the device instead of mirroring an existing one:

# Create a new virtual display
scrcpy --new-display

# Specify virtual display resolution
scrcpy --new-display=1920x1080

This uses the NewDisplayCapture server component, which creates an Android virtual display and captures its content.

Recording integration

Recording works independently of display and can capture to multiple container formats:

# Record video + audio to MP4
scrcpy --record=session.mp4

# Record audio only
scrcpy --no-video --record=audio.opus

# Record without display
scrcpy --no-playback --record=capture.mkv

Known issues (from GitHub)