scrcpy1

Usage

Overview

scrcpy provides display and control of Android devices connected on USB (or over TCP/IP). It does not require any root access.

Options

--always-on-top

Make scrcpy window always on top (above other windows).

--angle degrees

Rotate the video content by a custom angle, in degrees (clockwise).

--audio-bit-rate value

Encode the audio at the given bit rate, expressed in bits/s. Unit suffixes are supported: 'K' (x1000) and 'M' (x1000000).

Default is 128K (128000).

--audio-buffer ms

Configure the audio buffering delay (in milliseconds).

Lower values decrease the latency, but increase the likelihood of buffer underrun (causing audio glitches).

Default is 50.

--audio-codec name

Select an audio codec (opus, aac, flac or raw).

Default is opus.

--audio-codec-options key[:type]=value[,...]

Set a list of comma-separated key:type=value options for the device audio encoder.

The possible values for 'type' are 'int' (default), 'long', 'float' and 'string'.

The list of possible codec options is available in the Android documentation:

<https://d.android.com/reference/android/media/MediaFormat>

--audio-dup

Duplicate audio (capture and keep playing on the device).

This feature is only available with --audio-source=playback.

--audio-encoder name

Use a specific MediaCodec audio encoder (depending on the codec provided by --audio-codec).

The available encoders can be listed by --list-encoders.

--audio-source source

Select the audio source. Possible values are:

- "output": forwards the whole audio output, and disables playback on the device.
- "playback": captures the audio playback (Android apps can opt-out, so the whole output is not necessarily captured).
- "mic": captures the microphone.
- "mic-unprocessed": captures the microphone unprocessed (raw) sound.
- "mic-camcorder": captures the microphone tuned for video recording, with the same orientation as the camera if available.
- "mic-voice-recognition": captures the microphone tuned for voice recognition.
- "mic-voice-communication": captures the microphone tuned for voice communications (it will for instance take advantage of echo cancellation or automatic gain control if available).
- "voice-call": captures voice call.
- "voice-call-uplink": captures voice call uplink only.
- "voice-call-downlink": captures voice call downlink only.
- "voice-performance": captures audio meant to be processed for live performance (karaoke), includes both the microphone and the device playback.

Default is output.

--audio-output-buffer ms

Configure the size of the SDL audio output buffer (in milliseconds).

Do not change this setting unless you have a good reason.

Default is 10.

-b, --video-bit-rate value

Encode the video at the given bit rate, expressed in bits/s. Unit suffixes are supported: 'K' (x1000) and 'M' (x1000000).

Default is 8M (8000000).

--background-color hexcolor

Set the background color, encoded as hexadecimal color code (#RGB or #RRGGBB).

Default is #222 (dark gray).

--camera-ar ar

Select the camera size by its aspect ratio (+/- 10%).

Possible values are "sensor" (use the camera sensor aspect ratio), "num:den" (e.g. "4:3") and "value" (e.g. "1.6").

--camera-facing facing

Select the device camera by its facing direction.

Possible values are "front", "back" and "external".

--camera-fps fps

Specify the camera capture frame rate.

If not specified, Android's default frame rate (30 fps) is used.

--camera-high-speed

Enable high-speed camera capture mode.

This mode is restricted to specific resolutions and frame rates, listed by --list-camera-sizes.

--camera-id id

Specify the device camera id to mirror.

The available camera ids can be listed by --list-cameras.

--camera-size widthxheight

Specify an explicit camera capture size.

--camera-torch

Turn on the camera torch when the camera starts.

--camera-zoom zoom

Specify the camera zoom initial value.

--capture-orientation value

Possible values are 0, 90, 180, 270, flip0, flip90, flip180 and flip270, possibly prefixed by '@'.

The number represents the clockwise rotation in degrees; the "flip" keyword applies a horizontal flip before the rotation.

If a leading '@' is passed (@90) for display capture, then the rotation is locked, and is relative to the natural device orientation.

If '@' is passed alone, then the rotation is locked to the initial device orientation.

Default is 0.

--crop width:height:x:y

Crop the device screen on the server.

The values are expressed in the device natural orientation (typically, portrait for a phone, landscape for a tablet).

-d, --select-usb

Use USB device (if there is exactly one, like adb -d).

Also see -e (--select-tcpip).

--disable-screensaver

Disable screensaver while scrcpy is running.

--display-id id

Specify the device display id to mirror.

The available display ids can be listed by --list-displays.

Default is 0.

--display-ime-policy value

Set the policy for selecting where the IME should be displayed.

Possible values are "local", "fallback" and "hide":

- "local" means that the IME should appear on the local display.
- "fallback" means that the IME should appear on a fallback display (the default display).
- "hide" means that the IME should be hidden.

By default, the IME policy is left unchanged.

--display-orientation value

Set the initial display orientation.

Possible values are 0, 90, 180, 270, flip0, flip90, flip180 and flip270. The number represents the clockwise rotation in degrees; the "flip" keyword applies a horizontal flip before the rotation.

Default is 0.

-e, --select-tcpip

Use TCP/IP device (if there is exactly one, like adb -e).

Also see -d (--select-usb).

-f, --fullscreen

Start in fullscreen.

--force-adb-forward

Do not attempt to use "adb reverse" to connect to the device.

-G

Same as --gamepad=uhid, or --keyboard=aoa if --otg is set.

--gamepad mode

Select how to send gamepad inputs to the device.

Possible values are "disabled", "uhid" and "aoa":

- "disabled" does not send gamepad inputs to the device.
- "uhid" simulates physical HID gamepads using the Linux HID kernel module on the device.
- "aoa" simulates physical HID gamepads using the AOAv2 protocol. It may only work over USB.

Also see --keyboard and R--mouse.

-h, --help

Print this help.

--hwdec mode

Configure hardware video decoding on the computer.

Possible values are "auto" (the first available hardware decoder, software decoding otherwise), "disabled" (always use software decoding), "vaapi" (Linux only), "d3d11va" (Windows only) and "videotoolbox" (macOS only).

Default is "auto".

--ignore-video-encoder-constraints

Do not consider video encoder capabilities.

This is useful if the reported capabilities are incorrect.

It may help to force a value for --min-size-alignment.

-K

Same as --keyboard=uhid, or --keyboard=aoa if --otg is set.

--keep-active

Keep the screen on by simulating user activity.

--keyboard mode

Select how to send keyboard inputs to the device.

Possible values are "disabled", "sdk", "uhid" and "aoa":

- "disabled" does not send keyboard inputs to the device.
- "sdk" uses the Android system API to deliver keyboard events to applications.
- "uhid" simulates a physical HID keyboard using the Linux HID kernel module on the device.
- "aoa" simulates a physical HID keyboard using the AOAv2 protocol. It may only work over USB.

For "uhid" and "aoa", the keyboard layout must be configured (once and for all) on the device, via Settings -> System -> Languages and input -> Physical keyboard. This settings page can be started directly using the shortcut MOD+k (except in OTG mode), or by executing:

adb shell am start -a android.settings.HARD_KEYBOARD_SETTINGS

This option is only available when the HID keyboard is enabled (or a physical keyboard is connected).

Also see --mouse and --gamepad.

--kill-adb-on-close

Kill adb when scrcpy terminates.

--legacy-paste

Inject computer clipboard text as a sequence of key events on Ctrl+v (like MOD+Shift+v).

This is a workaround for some devices not behaving as expected when setting the device clipboard programmatically.

--list-apps

List Android apps installed on the device.

--list-camera-sizes

List the valid camera capture sizes.

--list-cameras

List cameras available on the device.

--list-encoders

List video and audio encoders available on the device.

--list-displays

List displays available on the device.

-m, --max-size value

Limit both the width and height of the video.

For display mirroring, the other dimension is computed so that the device aspect ratio is preserved (except for flex displays).

For camera mirroring, the value is used to select the camera source size instead.

Default is 0 (unlimited).

-M

Same as --mouse=uhid, or --mouse=aoa if --otg is set.

--max-fps value

Limit the framerate of screen capture (officially supported since Android 10, but may work on earlier versions).

--min-size-alignment alignment

Configure the minimum video size alignment.

This is a power-of-2 value (1, 2, 4, 8 or 16) that the video width and height must be multiples of.

The actual alignment will be the maximum of this value and the video codec's alignment requirement.

Default is 1.

--mouse mode

Select how to send mouse inputs to the device.

Possible values are "disabled", "sdk", "uhid" and "aoa":

- "disabled" does not send mouse inputs to the device.
- "sdk" uses the Android system API to deliver mouse events to applications.
- "uhid" simulates a physical HID mouse using the Linux HID kernel module on the device.
- "aoa" simulates a physical mouse using the AOAv2 protocol. It may only work over USB.

In "uhid" and "aoa" modes, the computer mouse is captured to control the device directly (relative mouse mode).

LAlt, LSuper or RSuper toggle the capture mode, to give control of the mouse back to the computer.

Also see --keyboard and --gamepad.

--mouse-bind xxxx[:xxxx]

Configure bindings of secondary clicks.

The argument must be one or two sequences (separated by ':') of exactly 4 characters, one for each secondary click (in order: right click, middle click, 4th click, 5th click).

The first sequence defines the primary bindings, used when a mouse button is pressed alone. The second sequence defines the secondary bindings, used when a mouse button is pressed while the Shift key is held.

If the second sequence of bindings is omitted, then it is the same as the first one.

Each character must be one of the following:

- '+': forward the click to the device
- '-': ignore the click
- 'b': trigger shortcut BACK (or turn screen on if off)
- 'h': trigger shortcut HOME
- 's': trigger shortcut APP_SWITCH
- 'n': trigger shortcut "expand notification panel"

Default is 'bhsn:++++' for SDK mouse, and '++++:bhsn' for AOA and UHID.

-n, --no-control

Disable device control (mirror the device in read-only).

-N, --no-playback

Disable video and audio playback on the computer (equivalent to --no-video-playback --no-audio-playback).

--new-display[=[widthxheight][/dpi]]

Create a new display with the specified resolution and density. If not provided, they default to the main display dimensions and DPI.

Examples:

--new-display=1920x1080
--new-display=1920x1080/420
--new-display # main display size and density
--new-display=/240 # main display size and 240 dpi

--no-audio

Disable audio forwarding.

--no-audio-playback

Disable audio playback on the computer.

--no-cleanup

By default, scrcpy removes the server binary from the device and restores the device state (show touches, stay awake and power mode) on exit.

This option disables this cleanup.

--no-clipboard-autosync

By default, scrcpy automatically synchronizes the computer clipboard to the device clipboard before injecting Ctrl+v, and the device clipboard to the computer clipboard whenever it changes.

This option disables this automatic synchronization.

--no-downsize-on-error

By default, on MediaCodec error, scrcpy automatically tries again with a lower definition.

This option disables this behavior.

--no-key-repeat

Do not forward repeated key events when a key is held down.

--no-mipmaps

If the renderer is OpenGL 3.0+ or OpenGL ES 2.0+, then mipmaps are automatically generated to improve downscaling quality. This option disables the generation of mipmaps.

--no-mouse-hover

Do not forward mouse hover (mouse motion without any clicks) events.

--no-power-on

Do not power on the device on start.

--no-terminal-title

Disable terminal title updates.

--no-vd-destroy-content

Disable virtual display "destroy content on removal" flag.

With this option, when the virtual display is closed, the running apps are moved to the main display rather than being destroyed.

--no-vd-system-decorations

Disable virtual display system decorations flag.

--no-video

Disable video forwarding.

--no-video-playback

Disable video playback on the computer.

--no-window

Disable scrcpy window. Implies --no-video-playback.

--no-window-aspect-ratio-lock

Disable window aspect ratio lock.

--orientation value

Same as --display-orientation=value --record-orientation=value.

--otg

Run in OTG mode: simulate physical keyboard and mouse, as if the computer keyboard and mouse were plugged directly to the device via an OTG cable.

In this mode, adb (USB debugging) is not necessary, and mirroring is disabled.

LAlt, LSuper or RSuper toggle the mouse capture mode, to give control of the mouse back to the computer.

Keyboard and mouse may be disabled separately using --keyboard=disabled and --mouse=disabled.

It may only work over USB.

See --keyboard, --mouse and --gamepad.

-p, --port port[:port]

Set the TCP port (range) used by the client to listen.

Default is 27183:27199.

--pause-on-exit[=mode]

Configure pause on exit. Possible values are "true" (always pause on exit), "false" (never pause on exit) and "if-error" (pause only if an error occurred).

This is useful to prevent the terminal window from automatically closing, so that error messages can be read.

Default is "false".

Passing the option without argument is equivalent to passing "true".

--power-off-on-close

Turn the device screen off when closing scrcpy.

--prefer-text

Inject alpha characters and space as text events instead of key events.

This avoids issues when combining multiple keys to enter special characters, but breaks the expected behavior of alpha keys in games (typically WASD).

--print-fps

Start FPS counter, to print framerate logs to the console. It can be started or stopped at any time with MOD+i.

--push-target path

Set the target directory for pushing files to the device by drag & drop. It is passed as-is to "adb push".

Default is "/sdcard/Download/".

-r, --record file

Record screen to file.

The format is determined by the --record-format option if set, or by the file extension.

--raw-key-events

Inject key events for all input keys, and ignore text events.

--record-format format

Force recording format (mp4, mkv, m4a, mka, opus, aac, flac or wav).

--record-orientation value

Set the record orientation.

Possible values are 0, 90, 180 and 270. The number represents the clockwise rotation in degrees.

Default is 0.

--render-driver name

Request SDL to use the given render driver (this is just a hint).

Supported names are currently "direct3d", "opengl", "opengles2", "opengles", "metal" and "software".

<https://wiki.libsdl.org/SDL_HINT_RENDER_DRIVER>

--render-fit mode

Set the render-fit mode to configure how the rendering fits the window.

Possible values are "letterbox", "stretched" and "unscaled":

- "letterbox": preserve the aspect ratio and fit the window as best as possible (black bars are added either at the top and bottom or at the sides if needed).
- "stretched": fit the window without preserving the aspect ratio.
- "unscaled": render the display without scaling.

Default is "letterbox", unless --flex-display is set, in which case it is "unscaled".

--require-audio

By default, scrcpy mirrors only the video if audio capture fails on the device. This option makes scrcpy fail if audio is enabled but does not work.

-s, --serial number

The device serial number. Mandatory only if several devices are connected to adb.

-S, --turn-screen-off

Turn the device screen off immediately.

--screen-off-timeout seconds

Set the screen off timeout while scrcpy is running (restore the initial value on exit).

--shortcut-mod key[+...]][,...]

Specify the modifiers to use for scrcpy shortcuts. Possible keys are "lctrl", "rctrl", "lalt", "ralt", "lsuper" and "rsuper".

Several shortcut modifiers can be specified, separated by ','.

For example, to use either LCtrl or LSuper for scrcpy shortcuts, pass "lctrl,lsuper".

Default is "lalt,lsuper" (left-Alt or left-Super).

--start-app name

Start an Android app, by its exact package name.

Add a '?' prefix to select an app whose name starts with the given name, case-insensitive (retrieving app names on the device may take some time):

scrcpy --start-app=?firefox

Add a '+' prefix to force-stop before starting the app:

scrcpy --new-display --start-app=+org.mozilla.firefox

Both prefixes can be used, in that order:

scrcpy --start-app=+?firefox

-t, --show-touches

Enable "show touches" on start, restore the initial value on exit.

It only shows physical touches (not clicks from scrcpy).

--tcpip[=[+]ip[:port]]

Configure and connect the device over TCP/IP.

If a destination address is provided, then scrcpy connects to this address before starting. The device must listen on the given TCP port (default is 5555).

If no destination address is provided, then scrcpy attempts to find the IP address and adb port of the current device (typically connected over USB), enables TCP/IP mode if necessary, then connects to this address before starting.

Prefix the address with a '+' to force a reconnection.

--time-limit seconds

Set the maximum mirroring time, in seconds.

--tunnel-host ip

Set the IP address of the adb tunnel to reach the scrcpy server. This option automatically enables --force-adb-forward.

Default is localhost.

--tunnel-port port

Set the TCP port of the adb tunnel to reach the scrcpy server. This option automatically enables --force-adb-forward.

Default is 0 (not forced): the local port used for establishing the tunnel will be used.

-v, --version

Print the version of scrcpy.

-V, --verbosity value

Set the log level ("verbose", "debug", "info", "warn" or "error").

Default is "info" for release builds, "debug" for debug builds.

--v4l2-sink /dev/videoN

Output to v4l2loopback device.

--v4l2-buffer ms

Add a buffering delay (in milliseconds) before pushing frames. This increases latency to compensate for jitter.

This option is similar to --video-buffer, but specific to V4L2 sink.

Default is 0 (no buffering).

--video-buffer ms

Add a buffering delay (in milliseconds) before displaying video frames.

This increases latency to compensate for jitter.

Default is 0 (no buffering).

--video-codec name

Select a video codec (h264, h265, av1, vp8 or vp9).

Default is h264.

--video-codec-options key[:type]=value[,...]

Set a list of comma-separated key:type=value options for the device video encoder.

The possible values for 'type' are 'int' (default), 'long', 'float' and 'string'.

The list of possible codec options is available in the Android documentation:

<https://d.android.com/reference/android/media/MediaFormat>

--video-encoder name

Use a specific MediaCodec video encoder (depending on the codec provided by --video-codec).

The available encoders can be listed by --list-encoders.

--video-source source

Select the video source (display or camera).

Camera mirroring requires Android 12+.

Default is display.

-w, --stay-awake

Keep the device on while scrcpy is running, when the device is plugged in.

--window-borderless

Disable window decorations (display borderless window).

--window-title text

Set a custom window title.

--window-x value

Set the initial window horizontal position.

Default is "auto".

--window-y value

Set the initial window vertical position.

Default is "auto".

--window-width value

Set the initial window width.

Default is 0 (automatic).

--window-height value

Set the initial window height.

Default is 0 (automatic).

-x, --flex-display

Continuously resize the virtual display to match the window.

Exit status

scrcpy will exit with code 0 on normal program termination. If an initial connection cannot be established, the exit code 1 will be returned. If the device disconnects while a session is active, exit code 2 will be returned.

Shortcuts

In the following list, MOD is the shortcut modifier. By default, it's (left) Alt or (left) Super, but it can be configured by --shortcut-mod (see above).

MOD+q

Quit

MOD+f, F11

Switch fullscreen mode

MOD+Left

Rotate display left

MOD+Right

Rotate display right

MOD+Shift+Left, MOD+Shift+Right

Flip display horizontally

MOD+Shift+Up, MOD+Shift+Down

Flip display vertically

MOD+z

Pause or re-pause display

MOD+Shift+z

Unpause display

MOD+Shift+r

Reset video capture/encoding

MOD+g

Resize window to 1:1 (pixel-perfect)

MOD+w, Double-click on black borders

Resize window to remove black borders

MOD+h, Home, Middle-click

Click on HOME

MOD+b, MOD+Backspace, Right-click (when screen is on)

Click on BACK

MOD+s

Click on APP_SWITCH

MOD+m

Click on MENU

MOD+Up

Click on VOLUME_UP

MOD+Down

Click on VOLUME_DOWN

MOD+p

Click on POWER (turn screen on/off)

Right-click (when screen is off)

Turn screen on

MOD+o

Turn device screen off (keep mirroring)

MOD+Shift+o

Turn device screen on

MOD+r

Rotate device screen

MOD+n

Expand notification panel

MOD+Shift+n

Collapse notification panel

Mod+c

Copy to clipboard (inject COPY keycode, Android >= 7 only)

Mod+x

Cut to clipboard (inject CUT keycode, Android >= 7 only)

MOD+v

Copy computer clipboard to device, then paste (inject PASTE keycode, Android >= 7 only)

MOD+Shift+v

Inject computer clipboard text as a sequence of key events

MOD+k

Open keyboard settings on the device (for HID keyboard only)

MOD+i

Enable/disable FPS counter (print frames/second in logs)

Ctrl+click-and-move

Pinch-to-zoom and rotate from the center of the screen

Shift+click-and-move

Tilt vertically (slide with 2 fingers)

Ctrl+Shift+click-and-move

Tilt horizontally (slide with 2 fingers)

Drag & drop APK file

Install APK from computer

Drag & drop non-APK file

Push file to device (see --push-target)

MOD+t

Turn on the camera torch (camera mode only)

MOD+Shift+t

Turn off the camera torch (camera mode only)

MOD+Up

Zoom camera in (camera mode only)

MOD+Down

Zoom camera out (camera mode only)

Environment

ADB

Path to adb.

ANDROID_SERIAL

Device serial to use if no selector (-s, -d, -e or --tcpip=addr) is specified.

SCRCPY_ICON_DIR

Path to the icon directory.

SCRCPY_SERVER_PATH

Path to the server binary.

WWW

<https://github.com/Genymobile/scrcpy>