Display and control your Android device
To receive a notification on new releases, click on Watch > Custom > Releases on the top.
scrcpy v1.22
Changes since v1.21:
Similar to the --hid-keyboard
(or -K
) added in scrcpy v1.20 (#2632), this release introduces a new option --hid-mouse
(or -M
) (#2916):
scrcpy -K # HID keyboard
scrcpy -M # HID mouse
scrcpy -KM # HID keyboard and mouse
The mouse is "captured": the mouse pointer disappears from the computer and appears on the Android device.
Special captures keys, either Alt or Super, toggle (disable or enable) the mouse capture. Use one of them to give the control of the mouse back to the computer.
These capture keys do not conflict with shortcuts, since a shortcut is always a combination of the MOD key and some other key, while the capture key triggers an action only if it is pressed and released alone.
Like HID keyboard, it works only when the device is connected via USB, and is only supported on Linux.
A new option --otg
(#2974) allows to run scrcpy with only physical keyboard (#2632) and mouse (#2916) simulation, without mirroring and without requiring adb (USB debugging), as if the computer keyboard and mouse were plugged directly to the device via an OTG cable.
scrcpy --otg
# Pass the serial if several USB devices are available
scrcpy --otg -s 0123456789abcdef
This opens a window (with just the scrcpy logo, there is no mirroring), which, when focused, fowards the keyboard and mouse to the device:
The mouse capture works the same as explained in the previous section.
Since it works even with USB debugging disabled (i.e. without adb), it could for example be used to enable USB debugging on a device with a broken touchscreen (to then run scrcpy normally).
Like HID keyboard and HID mouse, this feature works only when the device is connected via USB, and is only supported on Linux.
With HiDPI scaling on Windows, by default the quality was awful (#40, #2865).
The FAQ explained how to force correct HiDPI scaling by the application to fix the issue, but it was not convenient (and nobody reads the FAQ anyway).
On this new version, DPI awareness is enabled by default.
scrcpy
is a command line application, and is configured with command line arguments.
On Windows, the file explorer lacks an "open a terminal here" feature, to open a terminal in the scrcpy directory, ready to execute adb
or scrcpy
.
The release now contains a file open_a_terminal_here.bat
(#2970). Just double-click on it.
This will simplify passing arguments on Windows, and give a hint to users who don't know how to use the command line (remember, nobody reads the FAQ).
Some devices are not able to encode a video at the device screen definition. In that case, running scrcpy
without argument just failed with an error.
The solution is simple: reduce the resolution (scrcpy -m1024
for example), as explained in the FAQ (did I mention that nobody reads the FAQ?).
In this new version, if the encoder fails before the first video frame, then scrcpy automatically retries with a lower definition (#2947), so in most cases it should work without explicitly passing a size argument.
It's better when it works out-of-the-box.
To receive a notification on new releases, click on Watch > Releases only on the top.
scrcpy v1.21
Changes since v1.20:
NOTE: This version does not work on Windows 7 (#2838). A development version including a fix is available here: #2840.
Scrcpy uses adb
to communicate with the device. To use scrcpy wirelessly, the users had to find the device IP address and connect via TCP/IP using adb
directly.
For convenience, this version introduces a new option to configure TCP/IP connections automatically, with two variants.
If the device (accessible at 192.168.1.1 in this example) already listens on a port (typically 5555) for incoming adb connections, then run:
scrcpy --tcpip=192.168.1.1 # default port is 5555
scrcpy --tcpip=192.168.1.1:5555
If the adb TCP/IP mode is disabled (or if you don't know the IP address), connect the device over USB, then run:
scrcpy --tcpip # without arguments
It will automatically find the device IP address (by parsing adb shell ip route
), enable TCP/IP mode, then connects to the device before starting.
Two new options --tunnel-host
and --tunnel-port
(implemented by @RipleyTom) allow to connect to a remote ADB server. This allows for example to mirror a device plugged on another computer easily.
To connect to a remote ADB server (for example 192.168.1.2), make the server listen on all interfaces:
adb kill-server
adb -a nodaemon server start
# keep this open
Then, from another terminal, run scrcpy:
export ADB_SERVER_SOCKET=tcp:192.168.1.2:5037
scrcpy --tunnel-host=192.168.1.2
Note that all ADB communications between the server and the client are unencrypted.
To connect to a remote ADB server over the Internet, it is strongly recommended to use a SSH tunnel instead.
The way scrcpy was accessing to the settings is now blocked in Android 12 due to permission changes. In practice, --stay-awake
(#2671) and --show-touches
(#2788) were broken.
An alternative implementation (#2802) fixes the issue.
There are two kinds of events generated when typing text:
By default, letters are injected using key events, so that the keyboard behaves as expected in games (typically for WASD keys).
An option --prefer-text
allows to inject text events even for letters and space (see text injection preference).
This version introduces a new option (--raw-key-events
, #2831), which always injects key events and ignores all text events.
This will typically result in the insertion of wrong characters for some keyboard layouts, but it may help a lot with some others (e.g. Chinese).
This option is only meaningful for the default injection method: with HID keyboard (--hid-keyboard
), all keys are sent as scancodes.
Scrcpy v1.20 introduced an important regression on Windows, preventing to launch several scrcpy instances simultaneously on Windows (#2779). It is fixed (by #2783) in this new version.
To allow seamless copy-paste (see v1.15 highlights), on Ctrl+v, a request to synchronize the computer clipboard to the device clipboard is performed before injecting Ctrl+v.
But when HID keyboard (introduced in scrcpy v1.20), is enabled, the Ctrl+v injection is not sent on the same channel as the clipboard request, so they are not serialized, and may occur in any order. As a consequence, it could happen that the old clipboard content was pasted instead of the new one.
In v1.20, to minimize the probability of occurrence of the wrong order, a delay of 2 milliseconds was added before injecting Ctrl+v: e4163321f00bb3830c6049bdb6c1515e7cc668a0. Then it was increased to 5ms: 45b0f8123a52f5c73a5860d616f4ceba2766ca6a. But even with 5ms, the wrong behavior sometimes happens.
To handle it properly, this new version implements an acknowledgment mechanism, so that Ctrl+v is injected over AOA only after the clipboard synchronization request has been performed and acknowledged by the server (#2814).
This ensures that Ctrl+v with an HID keyboard always pastes the expected content.
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.
A new option --no-clipboard-autosync
disables this automatic synchronization. This also disables the acknowledgment mechanism described above.
The scrcpy shortcuts MOD+c, MOD+x and MOD+v still allow explicit copy, cut and paste, even in this mode.
To receive a notification on new releases, click on Watch > Releases only on the top.
scrcpy v1.20
Changes since v1.19:
Scrcpy used a low-definition XPM icon. Its source code was cool, but the result was awful.
This version introduces a new official icon (designed by @varlesh, author of the papirus icon theme):
By default, scrcpy uses Android key or text injection: it works everywhere, but is (basically) limited to ASCII characters.
It is now possible to simulate a physical USB keyboard (#2632 by @AlynxZhou): the virtual keyboard is disabled and it works for all characters and IME.
However, it only works if the device is connected by USB, and is currently only supported on Linux (you could help making it work on Windows and macOS).
To enable this mode:
scrcpy --hid-keyboard
scrcpy -K # short version
If it fails for some reason (for example because the device is not connected via USB), it automatically fallbacks to the default mode (with a log in the console). This allows to use the same command line options when connected over USB and TCP/IP.
In this mode, raw key events (scancodes) are sent to the device, independently of the host key mapping. Therefore, if your keyboard layout does not match, it must be configured on the Android device, in Settings → System → Languages and input → Physical keyboard.
Some command line options were first introduced with a short version:
-c
/--crop
-T
/--always-on-top
Since these are "advanced" features (not common enough), the short version of these options had been deprecated in scrcpy v1.11 two years ago. It's time to remove them (and it simplified some refactors). Only the long version remains.
To receive a notification on new releases, click on Watch > Releases only on the top.
scrcpy v1.19
Changes since v1.18:
This release brings a new feature to buffer the video stream for a given delay. This is especially useful for removing a source of stuttering for live-streaming.
To minimize latency, scrcpy was to always display a frame as soon as it is available, without waiting. This design decision is (on purpose) at the cost of jitter: the delay between frames is not preserved. Note that this does not impact recording (--record
), which writes the timestamps captured on the device.
However, some real-time use cases may benefit from compensating for jitter, by adding a small latency. For example, few tens of seconds of latency for live-streaming are not important, but jitter is noticeable. The may also improve the mirroring of a video playback.
For this purpose, scrcpy v1.19 introduces two new options:
scrcpy --display-buffer=50 # add 50 ms buffering for display
scrcpy --v4l2-buffer=500 # add 500 ms buffering for v4l2 sink
In practice, here is a graph showing the difference in smoothness with a buffer of 50ms on a wireless connection:
TL;DR: if you use scrcpy for live-streaming on Linux, use v4l2 with some buffering, and capture the V4L2 source via OBS:
scrcpy -b20M --no-display --v4l2-sink=/dev/video2 --v4l2-buffer=100
On other platforms, as a fallback, run scrcpy with some display buffer, then capture the window via OBS:
scrcpy -b20M --display-buffer=100
To receive a notification on new releases, click on Watch > Releases only on the top.
scrcpy v1.18
Changes since v1.17:
Since Android 12, creating a secure display with shell permissions is not permitted anymore (#2129). As a consequence, protected content may not be mirrored on Android 12. To avoid an immediate crash when mirroring a device with Android 12 (preview), create a non-secure display. This is basically a revert of the fix for #36.
Android 12 also required some changes from scrcpy to write to the settings, needed for --stay-awake
and --show-touches
(#2402).
On Linux, a V4L2 sink (#2268) allows to expose the device screen as a webcam on the computer.
Once a new video device is created with v4l2loopback
(for example /dev/video1
), scrcpy can expose the video stream as a webcam instead of (or in addition to) displaying it in a window:
scrcpy --v4l2-sink=/dev/video1 --no-display
More details here.
The stream can then be opened with any V4L2-capable software. This allows for example expose the device screen to your favorite video-conference tool or to capture it directly from OBS (select Video Capture Device (V4L2)
as a source).
The option to lock the video orientation now allows to lock the initial orientation. This avoids to pass an explicit orientation value.
It also simplifies V4L2 usage, which does not support video dimension changes.
On closing scrcpy, a new option to power off the device automatically (#824):
scrcpy --power-off-on-close
The 4th and 5th buttons were not used. Now, the 4th button triggers APP_SWITCH
and the 5th expands the notification panel on single click and the settings panel on double click (#2258, #2260, #2264).
The keyboard shortcut MOD+n+n has also been added to expand the settings panel.
When the scrcpy window is resized, black borders may be added to preserve the aspect ratio of the device screen. It is possible to automatically resize the window to remove them (MOD+w or double click).
However, it preserved the left-corner location of the window. Now, it preserves the device screen content location (#2387).
/sdcard/Download/
A file drag&drop to the scrcpy window used to push to /sdcard/
by default. Now the default is /sdcard/Download/
.
It can still be changed by --push-target
.
In verbose mode (scrcpy -Vverbose
), all input events sent to the device are printed in the console (#2371). This can be useful for debugging.
To receive a notification on new releases, click on Watch > Releases only on the top.
scrcpy v1.17
Changes since v1.16:
The options --show-touches
and --stay-awake
have been broken by internal API changes in Android 11. The implementation have been adapted to work properly.
By default, scrcpy injects BACK on right-click and HOME on middle-click.
A new option --forward-all-clicks
has been added to forward these clicks to the device instead.
Copy-paste have been improved by previous releases, especially v1.15.
However, setting the device clipboard programmatically does not work properly on some devices, causing confusing behavior (injecting PASTE does not paste the content set programmatically).
As a workaround, 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).
Scrcpy v1.15 added restoration of the power mode on exit, to avoid leaving the physical screen off (enabled by --turn-screen-off
or
MOD+o).
However, restoring the power mode while the device screen was off caused unexpected behaviors (even if the "screen off" feature was not used). Therefore, if the screen was off, don't try to restore the power mode, the state is already as expected.
Some devices provide several encoders, and some of them may not work well.
A new option --encoder
allows to select another available H.264 encoder.
Scrcpy is a command-line tool, so it does not suit Windows very well.
By default, running scrcpy.exe
opens a new console, which is closed as soon as the process terminates. To let the user a chance to read any error message, a "pause" was implemented on error, but this caused issues for scripting (#1875).
In addition, to avoid opening a new terminal, a separate binary was provided with a special linking flag.
To simplify, these hacks have been moved into Windows-specific wrapper scripts:
scrcpy.exe
is the main binary, with the same behavior as on other platforms (no pause on error)scrcpy-console.bat
is a simple wrapper script to pause on errorscrcpy-noconsole.vbs
a one-line VBS script to start scrcpy.exe
without a consoleTo receive a notification on new releases, click on Watch > Releases only on the top.
scrcpy v1.16
Changes since v1.15.1:
This is a long time requested feature (#24).
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.
Pasting (e.g. via Ctrl+v) was broken in some cases (#1658). The fix would have required a new hotfix version (v1.15.2), but since pinch-to-zoom is ready, just go for v1.16 right now.
In addition, some devices apparently do not support the WAKEUP key, so inject POWER on start to turn the device screen on.
To receive a notification on new releases, click on Watch > Releases only on the top.
scrcpy v1.15
Changes since v1.14:
Ctrl and Shift keys are now forwarded to the device.
This allows to trigger many shortcuts on the device itself. For example, Ctrl+t in Firefox opens a new tab, Ctrl+w closes the current tab. Ctrl+c or Ctrl+d can now be injected in Termux. Ctrl+z could be used to cancel an action, like a change in a text field for example.
This also greatly simplifies text selection, by using the keyboard (Shift+arrows, Ctrl+a…). And it makes copy-paste more straightforward (see below).
Since Ctrl is now forwarded to the device, scrcpy must use another shortcut modifier (called MOD in the documentation). By default, it's either (left) Alt or (left) Super.
The shortcut modifier can be changed by a command-line parameter (--shortcut-mod
). Here are some examples:
# use RCtrl for shortcuts
scrcpy --shortcut-mod=rctrl
# use either LAlt or RCtrl
scrcpy --shortcut-mod=lalt,rctrl
# use LCtrl+LAlt
scrcpy --shortcut-mod=lctrl+lalt
# use LCtrl+LAlt or Super
scrcpy --shortcut-mod=lctrl+lalt,lsuper,rsuper
Forwarding Ctrl brings a lot of changes and improvements regarding copy-paste:
The clipboard size has also been increased from 4k to 256k.
MOD+o (or --turn-screen-off
) allows to mirror with physical screen turned off.
However, the physical screen was not automatically restored on disconnection, which was annoying. Now it is.
In addition, on Android, pressing POWER cancels the effect of turn screen off. For convenience, scrcpy now attempts to maintain the screen off when it generates a POWER event (either via right-click or MOD+p).
When a key is hold pressed, the system generates repeated key events.
The repeat count is now correctly forwarded to Android, and an option (--no-key-repeat
) has been added to completely disable them. This mitigates keyboard lag in some games.
To receive a notification on new releases, click on Watch > Releases only on the top.
scrcpy v1.14
Changes since v1.13:
A new option has been added to prevent the device to sleep:
scrcpy --stay-awake
scrcpy -w # short option
This is especially useful when --turn-screen-off
/-S
is enabled, because the device screen will stay awake (no lock screen to unlock after some delay) with screen off:
scrcpy -Sw # turn sceen off and stay awake
The initial "stay awake" state is restored when scrcpy is closed. This is the case even on disconnection/unplug (a new mechanism has been implemented to cleanup on disconnection, --show-touches
also benefits from it).
The shortcut to turn the screen back on after --turn-screen-off
or Ctrl
+o
had been removed (8c8649cfcd710859ce18eab557ed2af8cedb9a42) due to issues on some devices. Of course, it was still possible to turn it back on using the power button (twice), but it was not very convenient.
Therefore, to turn the screen on, the shortcut Ctrl
+Shift
+o
has been reactivated in this release. In practice, it works on many devices (in fact, I could not reproduce the issue anymore).
Clipboard synchronization between the Android device and the computer allowed to transfer UTF-8 text, but copy-pasting required an annoying two-steps copy.
Now, you can copy a text on Android (long-press on a text field, then click COPY), and immediately press Ctrl
+v
on the computer to paste it.
In the other direction, Ctrl
+Shift
+v
, in addition to synchronizing the clipboards, now injects a PASTE command (if the device runs Android >= 7). This preserves UTF-8 text.
A rework of the rendering code (#1408) fixes the long-standing issue #15, causing wrong click locations on secondary monitors (especially on macOS).
On Windows, Ctrl+C in the terminal just killed the program, without any cleanup. This was particularly annoying while recording, because in that case the resulting file was corrupted (#818).
Pressing Ctrl+C on Windows now quits the app properly (like on the other platforms).
A new advanced option has been added to pass any raw option to MediaFormat
. This could be used for example to change the profile/level of the codec:
scrcpy --codec-options profile=1,level=4096
See #1226 and #1325.