# scrcpy User Guide

**Mirror and control your Android device from your desktop — no root required.**

scrcpy (short for "screen copy") displays and controls Android devices connected via USB or over TCP/IP from a Linux, Windows, or macOS computer. It renders video and audio in real time using SDL2 and FFmpeg, communicating with the device through ADB. A lightweight server component runs on the Android device to capture the screen and audio, streaming them back to the client for display.

| | |
|---|---|
| **Version** | 3.3.4 |
| **Platforms** | Linux, Windows, macOS |
| **Android** | API 21+ (Android 5.0+) |
| **License** | Apache 2.0 |
| **Root required** | No |

---

## Quick Start

Connect your Android device via USB, enable USB debugging in Developer Options, then run:

```bash
scrcpy
```

That's it. A window appears showing your device screen with full touch/keyboard control.

> [!TIP]
> If you have only one device connected, scrcpy finds it automatically. With multiple devices, specify one with `-s <serial>` or use `-d` for USB / `-e` for TCP/IP.

### 30-Second Setup Checklist

1. **Install scrcpy** on your computer (see [Installation](#installation) below)
2. **Enable USB debugging** on your Android device: Settings > About phone > tap "Build number" 7 times > Settings > Developer options > USB debugging ON
3. **Connect** via USB cable
4. **Authorize** the computer on the device when prompted
5. **Run** `scrcpy`

---

## Installation

=== "Linux"

**Debian/Ubuntu (apt):**

```bash
apt install scrcpy
```

**Arch Linux:**

```bash
pacman -S scrcpy
```

**Snap:**

```bash
snap install scrcpy
```

**Build from source:**

```bash
# Install dependencies
apt install ffmpeg libsdl2-2.0-0 adb meson ninja-build \
    libavcodec-dev libavformat-dev libavutil-dev libswresample-dev \
    libsdl2-dev libusb-1.0-0-dev

# Clone and build
git clone https://github.com/Genymobile/scrcpy
cd scrcpy
meson setup build --buildtype=release
ninja -C build
```

=== "Windows"

Download the latest release archive from the [GitHub Releases](https://github.com/Genymobile/scrcpy/releases) page. Extract the zip and run `scrcpy.exe` from the extracted directory.

Ensure `adb` is available. The release archive bundles `adb`, but if you need a separate installation, install the Android SDK Platform Tools and add them to your `PATH`.

=== "macOS"

**Homebrew:**

```bash
brew install scrcpy
```

You also need `adb`:

```bash
brew install android-platform-tools
```

> [!NOTE]
> scrcpy requires ADB (Android Debug Bridge) to communicate with the device. Most installation methods bundle or depend on ADB automatically.

---

## Configuration

scrcpy is configured entirely through command-line options and environment variables. There is no configuration file.

### Environment Variables

| Variable | Purpose |
|---|---|
| `ADB` | Path to a custom `adb` executable |
| `ANDROID_SERIAL` | Default device serial (used when no `-s` is given) |
| `SCRCPY_ICON_PATH` | Path to a custom program icon |
| `SCRCPY_SERVER_PATH` | Path to a custom server binary |

**Example — use a specific ADB binary:**

```bash
ADB=/opt/android-sdk/platform-tools/adb scrcpy
```

### Shortcut Modifier Key

The modifier key (referred to as MOD throughout this guide) defaults to left Alt or left Super (Windows key). Change it with `--shortcut-mod`:

```bash
# Use right Ctrl as MOD
scrcpy --shortcut-mod=rctrl

# Use either left Ctrl or left Alt
scrcpy --shortcut-mod=lctrl,lalt
```

### Verbosity / Logging

Control log output with `-V` or `--verbosity`:

```bash
scrcpy -V verbose    # Maximum detail
scrcpy -V debug
scrcpy -V info       # Default
scrcpy -V warn
scrcpy -V error      # Minimum detail
```

---

## Core Usage

### Display Mirroring

The default mode mirrors the device's primary display:

```bash
scrcpy
```

#### Limiting Resolution

Reduce resolution to save bandwidth or improve performance:

```bash
# Limit longest dimension to 1024 pixels
scrcpy -m 1024

# Limit longest dimension to 800 pixels
scrcpy --max-size 800
```

A value of `0` (the default) means unlimited — the native resolution is used.

#### Limiting Frame Rate

```bash
scrcpy --max-fps 30
```

#### Video Bit Rate

Default is 8 Mbps. Adjust for quality vs. performance:

```bash
scrcpy -b 2M        # Lower quality, less bandwidth
scrcpy -b 16M       # Higher quality, more bandwidth
```

#### Video Codec

Choose between H.264 (default), H.265, or AV1:

```bash
scrcpy --video-codec=h264    # Default, widest compatibility
scrcpy --video-codec=h265    # Better compression
scrcpy --video-codec=av1     # Best compression (requires device support)
```

#### Specific Video Encoder

Force a particular MediaCodec encoder on the device:

```bash
# List available encoders first
scrcpy --list-encoders

# Use a specific encoder
scrcpy --video-encoder='OMX.qcom.video.encoder.avc'
```

#### Advanced Video Codec Options

Pass key-value options to the underlying MediaCodec encoder:

```bash
scrcpy --video-codec-options=profile:int=8,level:int=64
```

#### Cropping

Crop the device screen to mirror only a region:

```bash
# Crop to 1080x1920 starting at coordinates (0, 0)
scrcpy --crop=1080:1920:0:0
```

Format: `width:height:x:y`

#### Display Orientation

Rotate or flip the display output:

```bash
scrcpy --display-orientation=90     # Rotate 90 degrees
scrcpy --display-orientation=180    # Rotate 180 degrees
scrcpy --display-orientation=flip0  # Horizontal flip
```

Valid values: `0`, `90`, `180`, `270`, `flip0`, `flip90`, `flip180`, `flip270`.

#### Capture Orientation

Control how the video capture is oriented. Prefix with `@` to lock the orientation:

```bash
scrcpy --capture-orientation=0
scrcpy --capture-orientation=@90    # Locked at 90 degrees
```

#### Rotate by Custom Angle

Rotate the video by an arbitrary angle (in degrees):

```bash
scrcpy --angle=45
```

#### Mirroring a Secondary Display

```bash
# List available displays
scrcpy --list-displays

# Mirror display #2
scrcpy --display-id=2
```

#### Video Buffering

Add buffering to smooth playback at the cost of latency:

```bash
scrcpy --video-buffer=200    # 200ms buffer (default 0)
```

> [!NOTE]
> The default video buffer is 0ms (no buffering), which gives the lowest latency. Increase it only if you experience stuttering.

---

### Audio Forwarding

scrcpy forwards device audio by default (requires Android 11+ for output capture).

#### Audio Source

```bash
scrcpy --audio-source=output       # Device audio output (default)
scrcpy --audio-source=playback     # Same as output, allows --audio-dup
scrcpy --audio-source=mic          # Device microphone
scrcpy --audio-source=mic-unprocessed
scrcpy --audio-source=mic-camcorder
scrcpy --audio-source=mic-voice-recognition
scrcpy --audio-source=mic-voice-communication
scrcpy --audio-source=voice-call
scrcpy --audio-source=voice-call-uplink
scrcpy --audio-source=voice-call-downlink
scrcpy --audio-source=voice-performance
```

#### Keep Audio Playing on Device

By default, forwarded audio is silenced on the device. To hear it on both:

```bash
scrcpy --audio-source=playback --audio-dup
```

> [!IMPORTANT]
> `--audio-dup` only works with `--audio-source=playback`.

#### Audio Codec

```bash
scrcpy --audio-codec=opus    # Default, best compression
scrcpy --audio-codec=aac
scrcpy --audio-codec=flac    # Lossless
scrcpy --audio-codec=raw     # Uncompressed
```

#### Audio Bit Rate

```bash
scrcpy --audio-bit-rate=64K    # Lower quality
scrcpy --audio-bit-rate=128K   # Default
scrcpy --audio-bit-rate=256K   # Higher quality
```

#### Audio Buffering

```bash
scrcpy --audio-buffer=100         # Capture buffer: 100ms (default 50)
scrcpy --audio-output-buffer=10   # SDL output buffer: 10ms (default 5)
```

#### Disable Audio

```bash
scrcpy --no-audio
```

#### Require Audio (Fail if Unavailable)

```bash
scrcpy --require-audio
```

#### Specific Audio Encoder

```bash
scrcpy --list-encoders
scrcpy --audio-encoder='OMX.google.opus.encoder'
```

#### Audio Codec Options

```bash
scrcpy --audio-codec-options=bitrate-mode:int=0
```

---

### Recording

Record the screen (and audio) to a file while mirroring:

```bash
scrcpy -r recording.mp4
scrcpy --record=recording.mkv
```

#### Record Without Displaying

```bash
scrcpy -Nr recording.mp4
```

This combines `--no-playback` (disables the window) with `--record`.

#### Record Format

The format is inferred from the file extension, or set explicitly:

```bash
scrcpy -r output --record-format=mkv
```

Supported formats:

| Format | Extension | Contents |
|---|---|---|
| MP4 | `.mp4` | Video + Audio |
| MKV | `.mkv` | Video + Audio |
| M4A | `.m4a` | Audio only |
| MKA | `.mka` | Audio only |
| Opus | `.opus` | Audio only |
| AAC | `.aac` | Audio only |
| FLAC | `.flac` | Audio only |
| WAV | `.wav` | Audio only |

#### Record Orientation

```bash
scrcpy -r recording.mp4 --record-orientation=90
```

---

### Camera Mirroring

Mirror a device camera instead of the screen (requires Android 12+):

```bash
scrcpy --video-source=camera
```

#### List Available Cameras

```bash
scrcpy --list-cameras
scrcpy --list-camera-sizes
```

#### Select a Camera

```bash
# By facing direction
scrcpy --video-source=camera --camera-facing=front
scrcpy --video-source=camera --camera-facing=back
scrcpy --video-source=camera --camera-facing=external

# By camera ID
scrcpy --video-source=camera --camera-id=0
```

#### Camera Resolution and Frame Rate

```bash
scrcpy --video-source=camera --camera-size=1920x1080
scrcpy --video-source=camera --camera-fps=60
```

#### Camera Aspect Ratio

```bash
scrcpy --video-source=camera --camera-ar=16:9
scrcpy --video-source=camera --camera-ar=sensor   # Match sensor ratio
```

#### High-Speed Camera

```bash
scrcpy --video-source=camera --camera-high-speed
```

> [!TIP]
> Camera mirroring does not capture the device screen. Combine it with recording (`-r`) to save camera footage directly to your computer.

---

### Input Control

scrcpy provides full control of the Android device via keyboard, mouse, and gamepad.

#### Keyboard Modes

| Mode | Flag | Description |
|---|---|---|
| SDK | `--keyboard=sdk` | Injects key events via Android SDK (default for normal mode) |
| UHID | `--keyboard=uhid` or `-K` | Creates a virtual HID keyboard on the device |
| AOA | `--keyboard=aoa` | USB accessory mode (USB only, no mirroring needed) |
| Disabled | `--keyboard=disabled` | No keyboard input |

```bash
scrcpy --keyboard=uhid
scrcpy -K                   # Shorthand for --keyboard=uhid
```

> [!TIP]
> UHID mode (`-K`) provides better key mapping and supports more key combinations than SDK mode. Use it when you need accurate keyboard input.

#### Mouse Modes

| Mode | Flag | Description |
|---|---|---|
| SDK | `--mouse=sdk` | Injects touch events (default for normal mode) |
| UHID | `--mouse=uhid` or `-M` | Creates a virtual HID mouse |
| AOA | `--mouse=aoa` | USB accessory mode |
| Disabled | `--mouse=disabled` | No mouse input |

```bash
scrcpy --mouse=uhid
scrcpy -M
```

#### Mouse Button Bindings

Configure what secondary mouse clicks do with `--mouse-bind`:

```bash
# Format: four characters for primary:secondary bindings
# b=back, h=home, s=app_switch, n=notification
scrcpy --mouse-bind=bhsn:++++    # Default for SDK mode
scrcpy --mouse-bind=++++:bhsn    # Default for UHID/AOA mode
```

Each position maps to: right-click, middle-click, 4th-click, 5th-click. `+` means default behavior (pass through).

#### Gamepad Mode

```bash
scrcpy --gamepad=uhid
scrcpy -G                   # Shorthand for --gamepad=uhid
```

| Mode | Flag |
|---|---|
| UHID | `--gamepad=uhid` or `-G` |
| AOA | `--gamepad=aoa` |
| Disabled | `--gamepad=disabled` |

#### Text Injection Preferences

```bash
scrcpy --prefer-text       # Inject alpha characters as text events
scrcpy --raw-key-events    # Inject key events for all input keys
scrcpy --legacy-paste      # Inject clipboard as key events on Ctrl+v
```

#### Disable Key Repeat

```bash
scrcpy --no-key-repeat
```

#### Disable Mouse Hover

```bash
scrcpy --no-mouse-hover
```

#### Disable All Control

```bash
scrcpy -n    # or --no-control (read-only mirror)
```

---

### Virtual Display

Create and mirror a virtual display instead of the physical screen:

```bash
scrcpy --new-display
scrcpy --new-display=1920x1080/420    # WxH/dpi
scrcpy --new-display=1280x720
```

#### Keep Content on Close

By default, apps on the virtual display are destroyed when scrcpy exits. To keep them:

```bash
scrcpy --new-display --no-vd-destroy-content
```

#### Disable System Decorations

```bash
scrcpy --new-display --no-vd-system-decorations
```

---

### Window Control

#### Window Title

```bash
scrcpy --window-title="My Phone"
```

#### Window Position and Size

```bash
scrcpy --window-x=100 --window-y=100
scrcpy --window-width=800 --window-height=600
```

#### Always on Top

```bash
scrcpy --always-on-top
```

#### Borderless Window

```bash
scrcpy --window-borderless
```

#### Fullscreen

```bash
scrcpy -f    # or --fullscreen
```

Toggle fullscreen at any time with **MOD+f**.

#### Render Driver

Force a specific rendering backend:

```bash
scrcpy --render-driver=opengl
scrcpy --render-driver=direct3d
scrcpy --render-driver=metal        # macOS
scrcpy --render-driver=software     # Software fallback
```

Available: `direct3d`, `opengl`, `opengles2`, `opengles`, `metal`, `software`.

#### Disable Mipmaps

```bash
scrcpy --no-mipmaps
```

---

### OTG Mode

Use the device as a USB input device without mirroring (USB connection required, no ADB needed):

```bash
scrcpy --otg
scrcpy --otg -K -M    # Keyboard and mouse in OTG mode (uses AOA)
```

> [!WARNING]
> OTG mode does not mirror the screen. It only forwards keyboard, mouse, and gamepad input via USB AOA protocol. The `-K`, `-M`, and `-G` shortcuts use AOA mode instead of UHID when `--otg` is specified.

---

### TCP/IP (Wireless) Connection

#### Setup from USB

```bash
scrcpy --tcpip
```

This automatically configures the device for TCP/IP on port 5555, then connects wirelessly.

#### Connect to a Known IP

```bash
scrcpy --tcpip=192.168.1.100
scrcpy --tcpip=192.168.1.100:5555
```

#### Force-Stop Before Reconnecting

```bash
scrcpy --tcpip=+192.168.1.100    # '+' prefix resets the connection
```

---

### Device Power Management

```bash
scrcpy -S                        # Turn screen off at start
scrcpy -Sw                       # Screen off + stay awake
scrcpy --power-off-on-close      # Turn screen off when scrcpy exits
scrcpy --no-power-on             # Don't power on device at start
scrcpy --screen-off-timeout=300  # Screen off timeout in seconds
```

---

### Clipboard

Clipboard is synchronized automatically between the computer and device (Android 7+).

```bash
scrcpy --no-clipboard-autosync    # Disable automatic clipboard sync
```

Manual clipboard operations via shortcuts:

| Shortcut | Action |
|---|---|
| MOD+c | Copy device clipboard |
| MOD+x | Cut from device |
| MOD+v | Paste computer clipboard to device |
| MOD+Shift+v | Inject clipboard text as key events |

---

### File Transfer

**Drag and drop** files onto the scrcpy window:

- **APK files** are installed on the device
- **Other files** are pushed to the device

The default push target is `/sdcard/Download/`. Change it:

```bash
scrcpy --push-target=/sdcard/Documents/
```

---

### App Management

#### List Installed Apps

```bash
scrcpy --list-apps
```

#### Start an App

```bash
scrcpy --start-app=com.example.myapp

# Fuzzy match (prefix with ?)
scrcpy --start-app='?myapp'

# Force-stop before starting (prefix with +)
scrcpy --start-app='+com.example.myapp'
```

---

### Display IME Policy

Control virtual keyboard behavior:

```bash
scrcpy --display-ime-policy=local       # Use local IME
scrcpy --display-ime-policy=fallback    # Fallback behavior
scrcpy --display-ime-policy=hide        # Hide IME
```

---

### V4L2 Output (Linux Only)

Send scrcpy video output to a v4l2loopback device for use as a virtual webcam:

```bash
scrcpy --v4l2-sink=/dev/video2
scrcpy --v4l2-sink=/dev/video2 --v4l2-buffer=500
```

---

### Miscellaneous Options

```bash
scrcpy --show-touches           # or -t: show touch indicators on device
scrcpy --disable-screensaver    # Prevent screensaver on computer
scrcpy --print-fps              # Print FPS to console
scrcpy --time-limit=120         # Stop after 120 seconds
scrcpy --no-cleanup             # Don't restore device state on exit
scrcpy --kill-adb-on-close      # Kill adb server when scrcpy exits
scrcpy --force-adb-forward      # Use forward instead of reverse tunneling
scrcpy --pause-on-exit          # Pause console on exit
scrcpy --pause-on-exit=if-error # Pause only on error
scrcpy --no-downsize-on-error   # Don't retry with lower resolution on error
```

#### Port Configuration

```bash
scrcpy -p 27183:27186    # Use specific TCP port range
```

#### Tunnel Configuration

```bash
scrcpy --tunnel-host=192.168.1.1 --tunnel-port=5037
```

---

## Keyboard Shortcuts Reference

All shortcuts use the MOD key, which is **left Alt** or **left Super** by default (configurable via `--shortcut-mod`).

### Navigation and Display

| Shortcut | Action |
|---|---|
| MOD+f | Toggle fullscreen |
| MOD+Left | Rotate display left |
| MOD+Right | Rotate display right |
| MOD+Shift+Left or MOD+Shift+Right | Flip display horizontally |
| MOD+Shift+Up or MOD+Shift+Down | Flip display vertically |
| MOD+g | Resize window to 1:1 (pixel-perfect) |
| MOD+w or double-click black borders | Resize to remove black borders |
| MOD+z | Pause / re-pause display |
| MOD+Shift+z | Unpause display |
| MOD+Shift+r | Reset video capture/encoding |
| MOD+i | Toggle FPS counter |
| MOD+r | Rotate device screen |

### Android Buttons

| Shortcut | Action |
|---|---|
| MOD+h or middle-click | HOME |
| MOD+b or MOD+Backspace or right-click (screen on) | BACK |
| MOD+s or 4th-click | APP_SWITCH |
| MOD+m | MENU |
| MOD+Up | VOLUME_UP |
| MOD+Down | VOLUME_DOWN |
| MOD+p | POWER (toggle screen) |
| Right-click (screen off) | Power on |
| MOD+o | Turn screen off (keep mirroring) |
| MOD+Shift+o | Turn screen on |

### Notifications

| Shortcut | Action |
|---|---|
| MOD+n or 5th-click | Expand notification panel |
| MOD+Shift+n | Collapse notification panel |

### Clipboard

| Shortcut | Action |
|---|---|
| MOD+c | Copy to computer (Android 7+) |
| MOD+x | Cut to computer (Android 7+) |
| MOD+v | Paste from computer (Android 7+) |
| MOD+Shift+v | Inject clipboard as key events |

### Touch Gestures

| Gesture | Action |
|---|---|
| Ctrl+click-and-move | Pinch-to-zoom from center |
| Shift+click-and-move | Tilt vertically (two-finger slide) |
| Ctrl+Shift+click-and-move | Tilt horizontally |

### Other

| Shortcut | Action |
|---|---|
| MOD+k | Open keyboard settings (HID keyboard mode only) |
| Drag and drop APK file | Install APK on device |
| Drag and drop other file | Push file to device |

---

## Common Tasks

### 1. Mirror Over Wi-Fi

```bash
# First time: connect USB, then switch to TCP/IP
scrcpy --tcpip

# Subsequent connections (device IP known)
scrcpy --tcpip=192.168.1.42
```

### 2. Record a Demo Video

```bash
scrcpy -r demo.mp4 --max-size=1080 --max-fps=30 -b 4M
```

### 3. Record Audio Only

```bash
scrcpy --no-video -r audio.opus --audio-codec=opus
scrcpy --no-video -r audio.flac --audio-codec=flac
```

### 4. Mirror at Low Latency

```bash
scrcpy -b 4M -m 800 --max-fps=60 --video-buffer=0 --audio-buffer=0
```

### 5. Use as a Webcam (Linux)

```bash
# Load v4l2loopback kernel module
sudo modprobe v4l2loopback

# Send scrcpy output to virtual camera
scrcpy --v4l2-sink=/dev/video2 --no-playback
```

### 6. Use Device Camera as Webcam

```bash
scrcpy --video-source=camera --camera-facing=front --camera-size=1280x720 -N --v4l2-sink=/dev/video2
```

### 7. Mirror Without Interaction (Read-Only)

```bash
scrcpy --no-control --always-on-top --window-title="Device Monitor"
```

### 8. Multiple Devices Simultaneously

```bash
# Terminal 1
scrcpy -s DEVICE_SERIAL_1

# Terminal 2
scrcpy -s DEVICE_SERIAL_2

# Or use USB/TCP/IP selectors
scrcpy -d    # USB device
scrcpy -e    # TCP/IP device
```

### 9. Start an App and Mirror

```bash
scrcpy --start-app=com.android.chrome
scrcpy --start-app='?chrome'            # Fuzzy match
scrcpy --start-app='+com.android.chrome' # Force-stop first
```

### 10. Unattended Recording (Headless)

```bash
scrcpy --no-playback --no-control -r recording.mp4 --time-limit=3600
```

This records for up to one hour with no window and no control input.

### 11. Screen Off Mirroring (Save Battery)

```bash
scrcpy -S -w
```

Turns the device screen off while keeping mirroring active, and prevents the device from sleeping.

### 12. Mirror a Virtual Display

```bash
scrcpy --new-display=1920x1080/240
```

Creates a 1920x1080 virtual display at 240 DPI.

### 13. High-Quality Recording

```bash
scrcpy -r hq.mkv --video-codec=h265 -b 20M --audio-codec=flac
```

### 14. Present on External Monitor (Always on Top, Fullscreen)

```bash
scrcpy -f --always-on-top --disable-screensaver
```

### 15. Install an APK Remotely

Drag and drop the `.apk` file onto the scrcpy window. The APK is installed on the device automatically.

---

## Troubleshooting

### Error: Device not found or not authorized

**Cause:** USB debugging is not enabled, the computer is not authorized, or the USB connection is faulty.

**Solution:**
1. Enable USB debugging: Settings > Developer options > USB debugging
2. Revoke USB debugging authorizations on device, reconnect, and re-authorize
3. Try a different USB cable or port
4. Verify with `adb devices` — the device should show as "device", not "unauthorized"

**Prevention:** Use a quality USB cable that supports data transfer (not charge-only).

### Error: Audio capture failed

**Cause:** Audio forwarding requires Android 11+. Older devices cannot capture audio output.

**Solution:**
```bash
scrcpy --no-audio
```

Or use microphone capture instead:
```bash
scrcpy --audio-source=mic
```

**Prevention:** Use `--no-audio` on Android 10 and below, or use `--require-audio` to fail fast if audio is needed.

### Error: Black screen while mirroring

**Cause:** Some apps (especially DRM-protected or banking apps) block screen capture via the `FLAG_SECURE` window flag. Referenced in [#4821](https://github.com/Genymobile/scrcpy/issues/4821).

**Solution:** There is no reliable workaround without root. The device manufacturer or app developer controls this restriction.

**Prevention:** Test with non-DRM apps to confirm scrcpy is working correctly.

### Error: Performance degradation with `-S` (screen off)

**Cause:** Some devices reduce GPU performance when the screen is off. Referenced in [#3376](https://github.com/Genymobile/scrcpy/issues/3376).

**Solution:**
- Try without `-S` to confirm performance returns to normal
- Use `--screen-off-timeout=1` to turn off the screen after 1 second instead of immediately

**Prevention:** Not all devices handle screen-off mirroring efficiently. Test on your specific device.

### Error: 30 FPS cap on Samsung/MediaTek devices

**Cause:** Some Samsung devices with MediaTek chipsets impose a hardware-level 30 FPS limit on the encoder. Referenced in [#6742](https://github.com/Genymobile/scrcpy/issues/6742).

**Solution:**
- Try a different video codec: `scrcpy --video-codec=h265`
- Try a different encoder: `scrcpy --list-encoders` then `scrcpy --video-encoder=<alternate>`
- Lower the resolution: `scrcpy -m 720`

**Prevention:** This is a device/chipset limitation and cannot always be resolved.

### Error: Connection refused over TCP/IP

**Cause:** The device is not listening on the expected TCP port, or a firewall blocks the connection.

**Solution:**
1. Reconnect via USB and run `scrcpy --tcpip` to re-enable TCP/IP mode
2. Verify the device port: `adb tcpip 5555`
3. Verify connectivity: `adb connect <device_ip>:5555`
4. Check that both computer and device are on the same network

**Prevention:** Wi-Fi connections are inherently less reliable than USB. Expect occasional reconnections.

### Error: Encoder error / MediaCodec error

**Cause:** The requested resolution or codec is not supported by the device encoder.

**Solution:**
```bash
# Let scrcpy retry with lower resolution
scrcpy

# Or manually reduce resolution
scrcpy -m 720

# Try a different codec
scrcpy --video-codec=h265
```

By default, scrcpy retries with a lower resolution on MediaCodec errors. Disable this with `--no-downsize-on-error`.

### Error: Lag / high latency over Wi-Fi

**Cause:** Wi-Fi bandwidth or latency is insufficient for the selected quality settings.

**Solution:**
```bash
scrcpy -b 2M -m 800 --max-fps=30
```

Reduce bit rate, resolution, and frame rate to match available bandwidth.

### Error: Mouse clicks not registering

**Cause:** Mouse mode mismatch or UHID mode not supported on older Android versions.

**Solution:**
```bash
# Use SDK mode (most compatible)
scrcpy --mouse=sdk

# Or try UHID mode
scrcpy --mouse=uhid
```

### Error: Keyboard input not working correctly

**Cause:** Character encoding issues with SDK keyboard injection.

**Solution:**
```bash
# Use UHID keyboard for better key mapping
scrcpy -K

# Or inject characters as text
scrcpy --prefer-text
```

> [!CAUTION]
> `--prefer-text` and `--raw-key-events` are mutually exclusive approaches. Choose one based on whether you need accurate character input or accurate key events.

### Error: Installation difficulties on macOS

**Cause:** Homebrew dependency issues or missing ADB. Referenced in [#2256](https://github.com/Genymobile/scrcpy/issues/2256).

**Solution:**
```bash
brew update
brew install scrcpy
brew install android-platform-tools
```

Verify ADB works independently: `adb version`

---

## FAQ

**Q: Does scrcpy require root access on my Android device?**

No. scrcpy does not require root. It uses standard ADB (Android Debug Bridge) which only needs USB debugging enabled in Developer Options.

**Q: What Android version do I need?**

Android 5.0 (API 21) or higher for screen mirroring. Audio forwarding requires Android 11+. Camera mirroring requires Android 12+.

**Q: Can I use scrcpy wirelessly?**

Yes. Use `scrcpy --tcpip` while connected via USB to set up wireless mode, or connect manually with `scrcpy --tcpip=<device_ip>`. Both computer and device must be on the same network.

**Q: Does scrcpy work with multiple devices?**

Yes. Run separate scrcpy instances, each targeting a different device with `-s <serial>`. Use `adb devices` to list connected devices and their serials.

**Q: Can I record the screen without showing the mirror window?**

Yes. Use `scrcpy -Nr recording.mp4` to record without displaying a window.

**Q: Why is the audio not working?**

Audio forwarding of device output requires Android 11+. On older devices, use `--no-audio` to disable it, or `--audio-source=mic` to capture microphone audio instead.

**Q: Can I copy/paste between my computer and Android device?**

Yes, on Android 7+. The clipboard syncs automatically. Use MOD+c to copy, MOD+v to paste. Disable auto-sync with `--no-clipboard-autosync`.

**Q: How do I change the keyboard shortcut modifier?**

Use `--shortcut-mod`. For example: `scrcpy --shortcut-mod=rctrl` to use right Ctrl, or `scrcpy --shortcut-mod=lctrl,lalt` for multiple options.

**Q: Can scrcpy mirror in portrait and landscape?**

Yes. scrcpy follows the device orientation automatically. You can also force rotation with `--display-orientation=90` or lock it with `--capture-orientation=@0`.

**Q: What are the exit codes?**

| Code | Meaning |
|---|---|
| 0 | Normal termination |
| 1 | Start failure |
| 2 | Device disconnected |

**Q: How do I use scrcpy as a webcam?**

On Linux, use v4l2loopback: `scrcpy --v4l2-sink=/dev/video2`. This sends the video feed to a virtual camera device usable by any video conferencing application.

**Q: What's the difference between SDK, UHID, and AOA input modes?**

- **SDK** injects events through the Android framework. Most compatible but may miss some key combinations.
- **UHID** creates a virtual HID device on Android. Better key/mouse fidelity, works over both USB and TCP/IP.
- **AOA** uses USB accessory protocol. Works without ADB (even in `--otg` mode) but requires a USB connection.

**Q: Can I use scrcpy without mirroring the screen (input only)?**

Yes. Use `--otg` mode for USB input-only (keyboard, mouse, gamepad) without screen mirroring or ADB.

**Q: How do I reduce latency?**

Keep buffer values at their defaults (video-buffer=0, audio-buffer=50), use USB instead of Wi-Fi, reduce resolution with `-m`, and lower bit rate with `-b`. The default settings are already optimized for low latency.

**Q: Does scrcpy support gamepads?**

Yes. Use `--gamepad=uhid` or `-G` to forward gamepad input to the device via virtual HID.

---

## Complete CLI Reference

### Short Options

| Flag | Long Form | Description | Default |
|---|---|---|---|
| `-b` | `--video-bit-rate` | Video bit rate | `8M` |
| `-d` | `--select-usb` | Use USB device | -- |
| `-e` | `--select-tcpip` | Use TCP/IP device | -- |
| `-f` | `--fullscreen` | Start in fullscreen | off |
| `-G` | -- | Shorthand for `--gamepad=uhid` (or `aoa` with `--otg`) | -- |
| `-h` | `--help` | Print help and exit | -- |
| `-K` | -- | Shorthand for `--keyboard=uhid` (or `aoa` with `--otg`) | -- |
| `-m` | `--max-size` | Limit video dimensions | `0` (unlimited) |
| `-M` | -- | Shorthand for `--mouse=uhid` (or `aoa` with `--otg`) | -- |
| `-n` | `--no-control` | Disable device control | off |
| `-N` | `--no-playback` | Disable video and audio playback | off |
| `-p` | `--port` | TCP port range for client | auto |
| `-r` | `--record` | Record to file | -- |
| `-s` | `--serial` | Device serial number | auto-detect |
| `-S` | `--turn-screen-off` | Turn device screen off at start | off |
| `-t` | `--show-touches` | Show touch indicators | off |
| `-v` | `--version` | Print version and exit | -- |
| `-V` | `--verbosity` | Log level | `info` |
| `-w` | `--stay-awake` | Keep device awake while plugged in | off |

### Long Options

| Flag | Default |
|---|---|
| `--always-on-top` | off |
| `--angle <degrees>` | -- |
| `--audio-bit-rate <value>` | `128K` |
| `--audio-buffer <ms>` | `50` |
| `--audio-codec <name>` | `opus` |
| `--audio-codec-options <key[:type]=value[,...]>` | -- |
| `--audio-dup` | off |
| `--audio-encoder <name>` | auto |
| `--audio-output-buffer <ms>` | `5` |
| `--audio-source <source>` | `output` |
| `--camera-ar <ar>` | -- |
| `--camera-facing <facing>` | -- |
| `--camera-fps <value>` | `30` |
| `--camera-high-speed` | off |
| `--camera-id <id>` | -- |
| `--camera-size <WxH>` | -- |
| `--capture-orientation <value>` | `0` |
| `--crop <W:H:X:Y>` | -- |
| `--disable-screensaver` | off |
| `--display-id <id>` | `0` |
| `--display-ime-policy <value>` | -- |
| `--display-orientation <value>` | `0` |
| `--force-adb-forward` | off |
| `--gamepad <mode>` | -- |
| `--keyboard <mode>` | -- |
| `--kill-adb-on-close` | off |
| `--legacy-paste` | off |
| `--list-apps` | -- |
| `--list-cameras` | -- |
| `--list-camera-sizes` | -- |
| `--list-displays` | -- |
| `--list-encoders` | -- |
| `--max-fps <value>` | -- |
| `--mouse <mode>` | -- |
| `--mouse-bind <xxxx[:xxxx]>` | SDK: `bhsn:++++`, UHID/AOA: `++++:bhsn` |
| `--new-display[=WxH[/dpi]]` | -- |
| `--no-audio` | off |
| `--no-audio-playback` | off |
| `--no-cleanup` | off |
| `--no-clipboard-autosync` | off |
| `--no-downsize-on-error` | off |
| `--no-key-repeat` | off |
| `--no-mipmaps` | off |
| `--no-mouse-hover` | off |
| `--no-power-on` | off |
| `--no-vd-destroy-content` | off |
| `--no-vd-system-decorations` | off |
| `--no-video` | off |
| `--no-video-playback` | off |
| `--no-window` | off |
| `--orientation <value>` | -- |
| `--otg` | off |
| `--pause-on-exit[=mode]` | `false` |
| `--power-off-on-close` | off |
| `--prefer-text` | off |
| `--print-fps` | off |
| `--push-target <path>` | `/sdcard/Download/` |
| `--raw-key-events` | off |
| `--record-format <format>` | auto (from extension) |
| `--record-orientation <value>` | `0` |
| `--render-driver <name>` | auto |
| `--require-audio` | off |
| `--screen-off-timeout <seconds>` | -- |
| `--shortcut-mod <key[+...][,...]>` | `lalt,lsuper` |
| `--start-app <name>` | -- |
| `--tcpip[=[+]ip[:port]]` | port `5555` |
| `--time-limit <seconds>` | -- |
| `--tunnel-host <ip>` | -- |
| `--tunnel-port <port>` | -- |
| `--v4l2-buffer <ms>` | `0` |
| `--v4l2-sink </dev/videoN>` | -- |
| `--video-buffer <ms>` | `0` |
| `--video-codec <name>` | `h264` |
| `--video-codec-options <key[:type]=value[,...]>` | -- |
| `--video-encoder <name>` | auto |
| `--video-source <source>` | `display` |
| `--window-borderless` | off |
| `--window-title <text>` | -- |
| `--window-x <value>` | auto |
| `--window-y <value>` | auto |
| `--window-width <value>` | `0` (auto) |
| `--window-height <value>` | `0` (auto) |

---

_Generated May 2026 from Genymobile/scrcpy at 247a37d. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._