README.md

    scrcpy (v1.18)

    Read in another language

    This application provides display and control of Android devices connected on USB (or over TCP/IP). It does not require any root access. It works on GNU/Linux, Windows and macOS.

    screenshot

    It focuses on:

    • lightness (native, displays only the device screen)
    • performance (30~60fps)
    • quality (1920×1080 or above)
    • low latency (35~70ms)
    • low startup time (~1 second to display the first image)
    • non-intrusiveness (nothing is left installed on the device)

    Requirements

    The Android device requires at least API 21 (Android 5.0).

    Make sure you enabled adb debugging on your device(s).

    On some devices, you also need to enable an additional option to control it using keyboard and mouse.

    Get the app

    Packaging status

    Summary

    • Linux: apt install scrcpy
    • Windows: download
    • macOS: brew install scrcpy

    Build from sources: BUILD (simplified process)

    Linux

    On Debian (testing and sid for now) and Ubuntu (20.04):

    apt install scrcpy

    A Snap package is available: scrcpy.

    For Fedora, a COPR package is available: scrcpy.

    For Arch Linux, an AUR package is available: scrcpy.

    For Gentoo, an Ebuild is available: scrcpy/.

    You could also build the app manually (simplified process).

    Windows

    For Windows, for simplicity, a prebuilt archive with all the dependencies (including adb) is available:

    It is also available in Chocolatey:

    choco install scrcpy
    choco install adb    # if you don't have it yet

    And in Scoop:

    scoop install scrcpy
    scoop install adb    # if you don't have it yet

    You can also build the app manually.

    macOS

    The application is available in Homebrew. Just install it:

    brew install scrcpy

    You need adb, accessible from your PATH. If you don't have it yet:

    brew install android-platform-tools

    It's also available in MacPorts, which sets up adb for you:

    sudo port install scrcpy

    You can also build the app manually.

    Run

    Plug an Android device, and execute:

    scrcpy

    It accepts command-line arguments, listed by:

    scrcpy --help

    Features

    Capture configuration

    Reduce size

    Sometimes, it is useful to mirror an Android device at a lower definition to increase performance.

    To limit both the width and height to some value (e.g. 1024):

    scrcpy --max-size 1024
    scrcpy -m 1024  # short version

    The other dimension is computed to that the device aspect ratio is preserved. That way, a device in 1920×1080 will be mirrored at 1024×576.

    Change bit-rate

    The default bit-rate is 8 Mbps. To change the video bitrate (e.g. to 2 Mbps):

    scrcpy --bit-rate 2M
    scrcpy -b 2M  # short version

    Limit frame rate

    The capture frame rate can be limited:

    scrcpy --max-fps 15

    This is officially supported since Android 10, but may work on earlier versions.

    Crop

    The device screen may be cropped to mirror only part of the screen.

    This is useful for example to mirror only one eye of the Oculus Go:

    scrcpy --crop 1224:1440:0:0   # 1224x1440 at offset (0,0)

    If --max-size is also specified, resizing is applied after cropping.

    Lock video orientation

    To lock the orientation of the mirroring:

    scrcpy --lock-video-orientation     # initial (current) orientation
    scrcpy --lock-video-orientation=0   # natural orientation
    scrcpy --lock-video-orientation=1   # 90° counterclockwise
    scrcpy --lock-video-orientation=2   # 180°
    scrcpy --lock-video-orientation=3   # 90° clockwise

    This affects recording orientation.

    The window may also be rotated independently.

    Encoder

    Some devices have more than one encoder, and some of them may cause issues or crash. It is possible to select a different encoder:

    scrcpy --encoder OMX.qcom.video.encoder.avc

    To list the available encoders, you could pass an invalid encoder name, the error will give the available encoders:

    scrcpy --encoder _

    Capture

    Recording

    It is possible to record the screen while mirroring:

    scrcpy --record file.mp4
    scrcpy -r file.mkv

    To disable mirroring while recording:

    scrcpy --no-display --record file.mp4
    scrcpy -Nr file.mkv
    # interrupt recording with Ctrl+C

    "Skipped frames" are recorded, even if they are not displayed in real time (for performance reasons). Frames are timestamped on the device, so packet delay variation does not impact the recorded file.

    v4l2loopback

    On Linux, it is possible to send the video stream to a v4l2 loopback device, so that the Android device can be opened like a webcam by any v4l2-capable tool.

    The module v4l2loopback must be installed:

    sudo apt install v4l2loopback-dkms

    To create a v4l2 device:

    sudo modprobe v4l2loopback

    This will create a new video device in /dev/videoN, where N is an integer (more options are available to create several devices or devices with specific IDs).

    To list the enabled devices:

    # requires v4l-utils package
    v4l2-ctl --list-devices
    
    # simple but might be sufficient
    ls /dev/video*

    To start scrcpy using a v4l2 sink:

    scrcpy --v4l2-sink=/dev/videoN
    scrcpy --v4l2-sink=/dev/videoN --no-display  # disable mirroring window
    scrcpy --v4l2-sink=/dev/videoN -N            # short version

    (replace N by the device ID, check with ls /dev/video*)

    Once enabled, you can open your video stream with a v4l2-capable tool:

    ffplay -i /dev/videoN
    vlc v4l2:///dev/videoN   # VLC might add some buffering delay

    For example, you could capture the video within OBS.

    Connection

    Wireless

    Scrcpy uses adb to communicate with the device, and adb can connect to a device over TCP/IP:

    1. Connect the device to the same Wi-Fi as your computer.

    2. Get your device IP address, in Settings → About phone → Status, or by executing this command:

      adb shell ip route | awk '{print $9}'
    3. Enable adb over TCP/IP on your device: adb tcpip 5555.

    4. Unplug your device.

    5. Connect to your device: adb connect DEVICE_IP:5555 (replace DEVICE_IP).

    6. Run scrcpy as usual.

    It may be useful to decrease the bit-rate and the definition:

    scrcpy --bit-rate 2M --max-size 800
    scrcpy -b2M -m800  # short version

    Multi-devices

    If several devices are listed in adb devices, you must specify the serial:

    scrcpy --serial 0123456789abcdef
    scrcpy -s 0123456789abcdef  # short version

    If the device is connected over TCP/IP:

    scrcpy --serial 192.168.0.1:5555
    scrcpy -s 192.168.0.1:5555  # short version

    You can start several instances of scrcpy for several devices.

    Autostart on device connection

    You could use AutoAdb:

    autoadb scrcpy -s '{}'

    SSH tunnel

    To connect to a remote device, it is possible to connect a local adb client to a remote adb server (provided they use the same version of the adb protocol):

    adb kill-server    # kill the local adb server on 5037
    ssh -CN -L5037:localhost:5037 -R27183:localhost:27183 your_remote_computer
    # keep this open

    From another terminal:

    scrcpy

    To avoid enabling remote port forwarding, you could force a forward connection instead (notice the -L instead of -R):

    adb kill-server    # kill the local adb server on 5037
    ssh -CN -L5037:localhost:5037 -L27183:localhost:27183 your_remote_computer
    # keep this open

    From another terminal:

    scrcpy --force-adb-forward

    Like for wireless connections, it may be useful to reduce quality:

    scrcpy -b2M -m800 --max-fps 15

    Window configuration

    Title

    By default, the window title is the device model. It can be changed:

    scrcpy --window-title 'My device'

    Position and size

    The initial window position and size may be specified:

    scrcpy --window-x 100 --window-y 100 --window-width 800 --window-height 600

    Borderless

    To disable window decorations:

    scrcpy --window-borderless

    Always on top

    To keep the scrcpy window always on top:

    scrcpy --always-on-top

    Fullscreen

    The app may be started directly in fullscreen:

    scrcpy --fullscreen
    scrcpy -f  # short version

    Fullscreen can then be toggled dynamically with MOD+f.

    Rotation

    The window may be rotated:

    scrcpy --rotation 1

    Possibles values are:

    • 0: no rotation
    • 1: 90 degrees counterclockwise
    • 2: 180 degrees
    • 3: 90 degrees clockwise

    The rotation can also be changed dynamically with MOD+ (left) and MOD+ (right).

    Note that scrcpy manages 3 different rotations:

    • MOD+r requests the device to switch between portrait and landscape (the current running app may refuse, if it does not support the requested orientation).
    • --lock-video-orientation changes the mirroring orientation (the orientation of the video sent from the device to the computer). This affects the recording.
    • --rotation (or MOD+/MOD+) rotates only the window content. This affects only the display, not the recording.

    Other mirroring options

    Read-only

    To disable controls (everything which can interact with the device: input keys, mouse events, drag&drop files):

    scrcpy --no-control
    scrcpy -n

    Display

    If several displays are available, it is possible to select the display to mirror:

    scrcpy --display 1

    The list of display ids can be retrieved by:

    adb shell dumpsys display   # search "mDisplayId=" in the output

    The secondary display may only be controlled if the device runs at least Android 10 (otherwise it is mirrored in read-only).

    Stay awake

    To prevent the device to sleep after some delay when the device is plugged in:

    scrcpy --stay-awake
    scrcpy -w

    The initial state is restored when scrcpy is closed.

    Turn screen off

    It is possible to turn the device screen off while mirroring on start with a command-line option:

    scrcpy --turn-screen-off
    scrcpy -S

    Or by pressing MOD+o at any time.

    To turn it back on, press MOD+Shift+o.

    On Android, the POWER button always turns the screen on. For convenience, if POWER is sent via scrcpy (via right-click or MOD+p), it will force to turn the screen off after a small delay (on a best effort basis). The physical POWER button will still cause the screen to be turned on.

    It can also be useful to prevent the device from sleeping:

    scrcpy --turn-screen-off --stay-awake
    scrcpy -Sw

    Show touches

    For presentations, it may be useful to show physical touches (on the physical device).

    Android provides this feature in Developers options.

    Scrcpy provides an option to enable this feature on start and restore the initial value on exit:

    scrcpy --show-touches
    scrcpy -t

    Note that it only shows physical touches (with the finger on the device).

    Disable screensaver

    By default, scrcpy does not prevent the screensaver to run on the computer.

    To disable it:

    scrcpy --disable-screensaver

    Input control

    Rotate device screen

    Press MOD+r to switch between portrait and landscape modes.

    Note that it rotates only if the application in foreground supports the requested orientation.

    Copy-paste

    Any time the Android clipboard changes, it is automatically synchronized to the computer clipboard.

    Any Ctrl shortcut is forwarded to the device. In particular:

    • Ctrl+c typically copies
    • Ctrl+x typically cuts
    • Ctrl+v typically pastes (after computer-to-device clipboard synchronization)

    This typically works as you expect.

    The actual behavior depends on the active application though. For example, Termux sends SIGINT on Ctrl+c instead, and K-9 Mail composes a new message.

    To copy, cut and paste in such cases (but only supported on Android >= 7):

    • MOD+c injects COPY
    • MOD+x injects CUT
    • MOD+v injects PASTE (after computer-to-device clipboard synchronization)

    In addition, MOD+Shift+v allows to inject the computer clipboard text as a sequence of key events. This is useful when the component does not accept text pasting (for example in Termux), but it can break non-ASCII content.

    WARNING: Pasting the computer clipboard to the device (either via Ctrl+v or MOD+v) copies the content into the device clipboard. As a consequence, any Android application could read its content. You should avoid to paste sensitive content (like passwords) that way.

    Some devices do not behave as expected when setting the device clipboard programmatically. An option --legacy-paste is provided to change the behavior of Ctrl+v and MOD+v so that they also inject the computer clipboard text as a sequence of key events (the same way as MOD+Shift+v).

    Pinch-to-zoom

    To simulate "pinch-to-zoom": Ctrl+click-and-move.

    More precisely, hold Ctrl while pressing the left-click button. Until the left-click button is released, all mouse movements scale and rotate the content (if supported by the app) relative to the center of the screen.

    Concretely, scrcpy generates additional touch events from a "virtual finger" at a location inverted through the center of the screen.

    Text injection preference

    There are two kinds of events generated when typing text:

    • key events, signaling that a key is pressed or released;
    • text events, signaling that a text has been entered.

    By default, letters are injected using key events, so that the keyboard behaves as expected in games (typically for WASD keys).

    But this may cause issues. If you encounter such a problem, you can avoid it by:

    scrcpy --prefer-text

    (but this will break keyboard behavior in games)

    Key repeat

    By default, holding a key down generates repeated key events. This can cause performance problems in some games, where these events are useless anyway.

    To avoid forwarding repeated key events:

    scrcpy --no-key-repeat

    Right-click and middle-click

    By default, right-click triggers BACK (or POWER on) and middle-click triggers HOME. To disable these shortcuts and forward the clicks to the device instead:

    scrcpy --forward-all-clicks

    File drop

    Install APK

    To install an APK, drag & drop an APK file (ending with .apk) to the scrcpy window.

    There is no visual feedback, a log is printed to the console.

    Push file to device

    To push a file to /sdcard/Download/ on the device, drag & drop a (non-APK) file to the scrcpy window.

    There is no visual feedback, a log is printed to the console.

    The target directory can be changed on start:

    scrcpy --push-target=/sdcard/Movies/

    Audio forwarding

    Audio is not forwarded by scrcpy. Use sndcpy.

    Also see issue #14.

    Shortcuts

    In the following list, MOD is the shortcut modifier. By default, it's (left) Alt or (left) Super.

    It can be changed using --shortcut-mod. Possible keys are lctrl, rctrl, lalt, ralt, lsuper and rsuper. For example:

    # use RCtrl for shortcuts
    scrcpy --shortcut-mod=rctrl
    
    # use either LCtrl+LAlt or LSuper for shortcuts
    scrcpy --shortcut-mod=lctrl+lalt,lsuper

    Super is typically the Windows or Cmd key.

    Action Shortcut
    Switch fullscreen mode MOD+f
    Rotate display left MOD+ (left)
    Rotate display right MOD+ (right)
    Resize window to 1:1 (pixel-perfect) MOD+g
    Resize window to remove black borders MOD+w | Double-left-click¹
    Click on HOME MOD+h | Middle-click
    Click on BACK MOD+b | Right-click²
    Click on APP_SWITCH MOD+s | 4th-click³
    Click on MENU (unlock screen) MOD+m
    Click on VOLUME_UP MOD+ (up)
    Click on VOLUME_DOWN MOD+ (down)
    Click on POWER MOD+p
    Power on Right-click²
    Turn device screen off (keep mirroring) MOD+o
    Turn device screen on MOD+Shift+o
    Rotate device screen MOD+r
    Expand notification panel MOD+n | 5th-click³
    Expand settings panel MOD+n+n | Double-5th-click³
    Collapse panels MOD+Shift+n
    Copy to clipboard⁴ MOD+c
    Cut to clipboard⁴ MOD+x
    Synchronize clipboards and paste⁴ MOD+v
    Inject computer clipboard text MOD+Shift+v
    Enable/disable FPS counter (on stdout) MOD+i
    Pinch-to-zoom Ctrl+click-and-move

    ¹Double-click on black borders to remove them.
    ²Right-click turns the screen on if it was off, presses BACK otherwise.
    ³4th and 5th mouse buttons, if your mouse has them.
    ⁴Only on Android >= 7.

    Shortcuts with repeated keys are executted by releasing and pressing the key a second time. For example, to execute "Expand settings panel":

    1. Press and keep pressing MOD.
    2. Then double-press n.
    3. Finally, release MOD.

    All Ctrl+key shortcuts are forwarded to the device, so they are handled by the active application.

    Custom paths

    To use a specific adb binary, configure its path in the environment variable ADB:

    ADB=/path/to/adb scrcpy

    To override the path of the scrcpy-server file, configure its path in SCRCPY_SERVER_PATH.

    Why scrcpy?

    A colleague challenged me to find a name as unpronounceable as gnirehtet.

    strcpy copies a string; scrcpy copies a screen.

    How to build?

    See BUILD.

    Common issues

    See the FAQ.

    Developers

    Read the developers page.

    Licence

    Copyright (C) 2018 Genymobile
    Copyright (C) 2018-2021 Romain Vimont
    
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
    
        http://www.apache.org/licenses/LICENSE-2.0
    
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

    Articles

    Translations

    This README is available in other languages:

    Only this README file is guaranteed to be up-to-date.

    项目简介

    🚀 Github 镜像仓库 🚀

    源项目地址

    https://github.com/Genymobile/scrcpy

    发行版本 22

    scrcpy v1.18

    全部发行版

    贡献者 83

    全部贡献者

    开发语言

    • C 64.7 %
    • Java 29.9 %
    • Roff 1.6 %
    • Meson 1.4 %
    • Makefile 1.3 %