scrcpy(1) | General Commands Manual | scrcpy(1) |
NAME
scrcpy - Display and control your Android device
SYNOPSIS
scrcpy [options]
DESCRIPTION
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).
- --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:
- --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 (output, mic or playback).
The "output" source forwards the whole audio output, and disables playback on the device.
The "playback" source captures the audio playback (Android apps can opt-out, so the whole output is not necessarily captured).
The "mic" source captures the microphone.
Default is output.
- --audio-output-buffer ms
- Configure the size of the SDL audio output buffer (in milliseconds).
If you get "robotic" audio playback, you should test with a higher value (10). Do not change this setting otherwise.
Default is 5.
- -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).
- --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-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-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-size widthxheight
- Specify an explicit camera capture size.
- --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). Any --max-size value is computed on the cropped size.
- -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-buffer ms
- Add a buffering delay (in milliseconds) before displaying. This increases
latency to compensate for jitter.
Default is 0 (no buffering).
- --display-id id
- Specify the device display id to mirror.
The available display ids can be listed by --list-displays.
Default is 0.
- --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 --keyboardand R--mouse.
- -h, --help
- Print this help.
- -K
- Same as --keyboard=uhid, or --keyboard=aoa if --otg is set.
- --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_SETTINGSThis 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-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.
- --lock-video-orientation[=value]
- Lock capture video orientation to value.
Possible values are "unlocked", "initial" (locked to the initial orientation), 0, 90, 180, and 270. The values represent the clockwise rotation from the natural device orientation, in degrees.
Default is "unlocked".
Passing the option without argument is equivalent to passing "initial".
- -m, --max-size value
- Limit both the width and height of the video to value. The other
dimension is computed so that the device aspect-ratio is preserved.
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).
- --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).
- --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-video
- Disable video forwarding.
- --no-video-playback
- Disable video playback on the computer.
- --no-window
- Disable scrcpy window. Implies --no-video-playback and --no-control.
- --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.
If any of --hid-keyboard or --hid-mouse is set, only enable keyboard or mouse respectively, otherwise enable both.
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".
- --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.
- --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).
- -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 reconnect 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.
- --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.
It requires to lock the video orientation (see --lock-video-orientation).
- --v4l2-buffer ms
- Add a buffering delay (in milliseconds) before pushing frames. This
increases latency to compensate for jitter.
This option is similar to --display-buffer, but specific to V4L2 sink.
Default is 0 (no buffering).
- --video-codec name
- Select a video codec (h264, h265 or av1).
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:
- --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).
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+f
- 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+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 (slide vertically with two fingers)
- Drag & drop APK file
- Install APK from computer
- Drag & drop non-APK file
- Push file to device (see --push-target)
Environment variables
- ADB
- Path to adb.
- ANDROID_SERIAL
- Device serial to use if no selector (-s, -d, -e or --tcpip=addr) is specified.
- SCRCPY_ICON_PATH
- Path to the program icon.
- SCRCPY_SERVER_PATH
- Path to the server binary.
AUTHORS
scrcpy is written by Romain Vimont.
This manual page was written by Yangfl for the Debian Project (and may be used by others).
REPORTING BUGS
Report bugs to https://github.com/Genymobile/scrcpy/issues.
COPYRIGHT
Copyright © 2018 Genymobile https://www.genymobile.com
Copyright © 2018-2024 Romain Vimont <rom@rom1v.com>
Licensed under the Apache License, Version 2.0.