Skip to main content

​
Prerequisites

Before you begin, ensure you have the following tools installed:

Android Studio

Latest stable version (Arctic Fox or newer)

JDK 11+

Java Development Kit version 11 or higher

Android SDK

API Level 21 (Lollipop) through API Level 31

Git

For version control

​
SDK Requirements

The project requires the following Android SDK components:
  • Min SDK Version: 21 (Android 5.0 Lollipop)
  • Target SDK Version: 31 (Android 12)
  • Compile SDK Version: 31

​
Cloning the Repository

Clone the repository and navigate to the project directory: 
git clone https://github.com/zwc456baby/ScrcpyForAndroid.git
cd ScrcpyForAndroid
Make sure you have sufficient disk space (at least 2GB) for the Android SDK and build outputs.

​
Project Structure

Scrcpy for Android is organized as a multi-module Gradle project: 
ScrcpyForAndroid/
├── app/                    # Main Android application module
│   ├── src/main/
│   │   ├── java/          # Java source files
│   │   ├── res/           # Resources (layouts, drawables, etc.)
│   │   ├── assets/        # Contains scrcpy-server.jar
│   │   └── jniLibs/       # Native libraries
│   └── build.gradle       # App module build configuration
├── server/                # Server module (runs on target device)
│   ├── src/main/
│   │   ├── java/          # Server implementation
│   │   └── aidl/          # Android Interface Definition Language files
│   └── build.gradle       # Server module build configuration
├── build.gradle           # Root project build configuration
├── settings.gradle        # Project modules configuration
└── gradle.properties      # Gradle build properties

​
Key Modules

The main Android application that runs on the controlling device. It handles:
  • User interface and input
  • ADB connection management
  • Display rendering
  • Touch event forwarding
Package: org.client.scrcpy
The server component that gets deployed to the target device. It handles:
  • Screen capture via MediaCodec
  • Touch event injection
  • Device control operations
Package: org.server.scrcpyThe server is built as an APK and copied to app/src/main/assets/scrcpy-server.jar.

​
Building the Project

​
Using Android Studio

  1. Import the Project
    • Open Android Studio
    • Select “Open an Existing Project”
    • Navigate to the cloned repository directory
    • Click “OK” and wait for Gradle sync to complete
  2. Configure Build Variant
    • Open “Build Variants” panel (usually on the left side)
    • Select scrcpyDebug for development or scrcpyRelease for production builds
  3. Build the Application
    • Click “Build” → “Make Project” (Ctrl+F9 / Cmd+F9)
    • Or click “Build” → “Build Bundle(s) / APK(s)” → “Build APK(s)“

​
Using Command Line

The project uses Gradle 8.6. Build both modules using the Gradle wrapper: 
# Build debug APK (includes both server and app modules)
./gradlew assembleDebug

# Output: app/build/outputs/apk/scrcpy/debug/scrcpy-scrcpy-debug.apk
Release builds require signing configuration in local.properties or environment variables:
  • SIGNING_STORE_PASSWORD
  • SIGNING_KEY_ALIAS
  • SIGNING_KEY_PASSWORD

​
Build Process Details

The build process follows these steps:
  1. Server Module Build (server:assembleDebug or server:assembleRelease)
    • Compiles AIDL interfaces
    • Builds server APK
  2. Server Copy Task (server:copyServer)
    • Copies the built server APK to app/src/main/assets/
    • Renames it to scrcpy-server.jar
  3. App Module Build (app:assembleDebug or app:assembleRelease)
    • Compiles application code
    • Packages resources and assets (including server JAR)
    • Generates final APK
The app module automatically depends on server module builds through the tasks.whenTaskAdded hook in app/build.gradle:52-53.

​
Running on Device/Emulator

​
Install via Android Studio

  1. Connect your Android device via USB or start an emulator
  2. Enable Developer Options and USB Debugging on your device
  3. Click the “Run” button (green triangle) or press Shift+F10
  4. Select your target device from the deployment dialog

​
Install via Command Line

# Install debug build
./gradlew installScrcpyDebug

# Or use adb directly
adb install app/build/outputs/apk/scrcpy/debug/scrcpy-scrcpy-debug.apk

# Launch the app
adb shell am start -n org.client.scrcpy/.App

​
Testing the App

To test the screen mirroring functionality:
  1. Prepare Target Device
    • Ensure both devices are on the same local network
    • Enable “ADB over Network” or “Wireless ADB” on the target device
    • Note the IP address (usually shown in Developer Options)
  2. Connect
    • Open Scrcpy for Android on your controlling device
    • Enter the target device IP address
    • Select display parameters (1280x720 @ 2Mbps recommended)
    • Tap “Start”
  3. Accept ADB Prompt
    • Accept the ADB connection prompt on the target device
    • Check “Always allow from this computer” for convenience

​
Debugging Tips

​
Logcat Filtering

Use Android Studio’s Logcat or adb to filter logs: 
# Filter by package
adb logcat org.client.scrcpy:V *:S

# Filter by tag
adb logcat -s ScrcpyClient

# Save logs to file
adb logcat -d > scrcpy_logs.txt

​
Common Build Issues

Solution:
  • Check your internet connection
  • Invalidate caches: File → Invalidate Caches / Restart
  • Ensure JDK 11+ is configured in Android Studio settings
Solution:
# Manually build and copy server
./gradlew :server:assembleDebug :server:copyServer
Verify the file exists at app/src/main/assets/scrcpy-server.jar
Solution:
  • Ensure all ABIs are present in app/src/main/jniLibs/
  • Check that native libraries match your device architecture
  • Clean and rebuild: ./gradlew clean assembleDebug
Solution:
  • For debug builds, signing is automatic
  • For release builds, either:
    • Create local.properties with signing credentials
    • Set environment variables before building
    • Or modify app/build.gradle to remove signing requirement

​
Enable Verbose Logging

Add to gradle.properties: 
org.gradle.logging.level=debug

​
Debugging Native Code

If working with JNI libraries:
  1. Install LLDB debugger in Android Studio SDK Manager
  2. Set breakpoints in native code
  3. Run app in debug mode with Native debugger attached

​
Next Steps

Once your environment is set up:

Read Guidelines

Learn about code style and contribution workflow

Explore Architecture

Understand the application architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us