> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zwc456baby/ScrcpyForAndroid/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Setup

> Set up your development environment to contribute to Scrcpy for Android

## Prerequisites

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

<CardGroup cols={2}>
  <Card title="Android Studio" icon="android">
    Latest stable version (Arctic Fox or newer)
  </Card>

  <Card title="JDK 11+" icon="java">
    Java Development Kit version 11 or higher
  </Card>

  <Card title="Android SDK" icon="mobile">
    API Level 21 (Lollipop) through API Level 31
  </Card>

  <Card title="Git" icon="git">
    For version control
  </Card>
</CardGroup>

### 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:

```bash theme={null}
git clone https://github.com/zwc456baby/ScrcpyForAndroid.git
cd ScrcpyForAndroid
```

<Note>
  Make sure you have sufficient disk space (at least 2GB) for the Android SDK and build outputs.
</Note>

## 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

<AccordionGroup>
  <Accordion title="app" icon="mobile-screen">
    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`
  </Accordion>

  <Accordion title="server" icon="server">
    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.scrcpy`

    The server is built as an APK and copied to `app/src/main/assets/scrcpy-server.jar`.
  </Accordion>
</AccordionGroup>

## 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:

<CodeGroup>
  ```bash Debug Build theme={null}
  # Build debug APK (includes both server and app modules)
  ./gradlew assembleDebug

  # Output: app/build/outputs/apk/scrcpy/debug/scrcpy-scrcpy-debug.apk
  ```

  ```bash Release Build theme={null}
  # Build release APK (requires signing configuration)
  ./gradlew assembleRelease

  # Output: app/build/outputs/apk/scrcpy/release/scrcpy-scrcpy-release.apk
  ```

  ```bash Clean Build theme={null}
  # Clean previous builds and rebuild
  ./gradlew clean assembleDebug
  ```
</CodeGroup>

<Warning>
  Release builds require signing configuration in `local.properties` or environment variables:

  * `SIGNING_STORE_PASSWORD`
  * `SIGNING_KEY_ALIAS`
  * `SIGNING_KEY_PASSWORD`
</Warning>

### 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

<Tip>
  The app module automatically depends on server module builds through the `tasks.whenTaskAdded` hook in `app/build.gradle:52-53`.
</Tip>

## 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

```bash theme={null}
# 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:

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Gradle sync failed" icon="triangle-exclamation">
    **Solution**:

    * Check your internet connection
    * Invalidate caches: File → Invalidate Caches / Restart
    * Ensure JDK 11+ is configured in Android Studio settings
  </Accordion>

  <Accordion title="Server JAR not found" icon="file-slash">
    **Solution**:

    ```bash theme={null}
    # Manually build and copy server
    ./gradlew :server:assembleDebug :server:copyServer
    ```

    Verify the file exists at `app/src/main/assets/scrcpy-server.jar`
  </Accordion>

  <Accordion title="Native library loading errors" icon="book-open-cover">
    **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`
  </Accordion>

  <Accordion title="Signing configuration errors" icon="key">
    **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
  </Accordion>
</AccordionGroup>

### Enable Verbose Logging

Add to `gradle.properties`:

```properties theme={null}
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:

<CardGroup cols={2}>
  <Card title="Read Guidelines" icon="book" href="/contributing/guidelines">
    Learn about code style and contribution workflow
  </Card>

  <Card title="Explore Architecture" icon="sitemap" href="/development/overview">
    Understand the application architecture
  </Card>
</CardGroup>