Display and control your Android device
Improve README
Gitoffthelawn3c8ebf9abd44
diff --git a/README.md b/README.mdindex 7eb6cea6..66c8924b 100644--- a/README.md+++ b/README.md@@ -7,7 +7,7 @@ _pronounced "**scr**een **c**o**py**"_[Read in another language](#translations)This application provides display and control of Android devices connected via-USB (or [over TCP/IP](#tcpip-wireless)). It does not require any _root_ access.+USB or [over TCP/IP](#tcpip-wireless). It does not require any _root_ access.It works on _GNU/Linux_, _Windows_ and _macOS_.@@ -19,7 +19,7 @@ It focuses on:- **quality**: 1920×1080 or above- **low latency**: [35~70ms][lowlatency]- **low startup time**: ~1 second to display the first image- - **non-intrusiveness**: nothing is left installed on the device+ - **non-intrusiveness**: nothing is left installed on the Android device- **user benefits**: no account, no ads, no internet required- **freedom**: free and open source software@@ -27,10 +27,10 @@ It focuses on:Its features include:- [recording](#recording)- - mirroring with [device screen off](#turn-screen-off)+ - mirroring with [Android device screen off](#turn-screen-off)- [copy-paste](#copy-paste) in both directions- [configurable quality](#capture-configuration)- - device screen [as a webcam (V4L2)](#v4l2loopback) (Linux-only)+ - Android device [as a webcam (V4L2)](#v4l2loopback) (Linux-only)- [physical keyboard simulation (HID)](#physical-keyboard-simulation-hid)- [physical mouse simulation (HID)](#physical-mouse-simulation-hid)- [OTG mode](#otg)@@ -40,12 +40,12 @@ Its features include:The Android device requires at least API 21 (Android 5.0).-Make sure you [enabled adb debugging][enable-adb] on your device(s).+Make sure you [enable adb debugging][enable-adb] on your device(s).[enable-adb]: https://developer.android.com/studio/command-line/adb.html#EnablingOn some devices, you also need to enable [an additional option][control] to-control it using keyboard and mouse.+control it using a keyboard and mouse.[control]: https://github.com/Genymobile/scrcpy/issues/70#issuecomment-373286323@@ -97,14 +97,14 @@ For Gentoo, an [Ebuild] is available: [`scrcpy/`][ebuild-link].[Ebuild]: https://wiki.gentoo.org/wiki/Ebuild[ebuild-link]: https://github.com/maggu2810/maggu2810-overlay/tree/master/app-mobilephone/scrcpy-You could also [build the app manually][BUILD] ([simplified+You can also [build the app manually][BUILD] ([simplifiedprocess][BUILD_simple]).### Windows-For Windows, for simplicity, a prebuilt archive with all the dependencies-(including `adb`) is available:+For Windows, a prebuilt archive with all the dependencies (including `adb`) is+available:- [`scrcpy-win64-v1.23.zip`][direct-win64]_(SHA-256: d2f601b1d0157faf65153d8a093d827fd65aec5d5842d677ac86fb2b5b7704cc)_@@ -148,7 +148,7 @@ 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:+It's also available in [MacPorts], which sets up `adb` for you:```bashsudo port install scrcpy@@ -162,7 +162,7 @@ You can also [build the app manually][BUILD].## Run-Plug an Android device, and execute:+Plug an Android device into your computer, and execute:```bashscrcpy@@ -180,7 +180,7 @@ scrcpy --help#### Reduce size-Sometimes, it is useful to mirror an Android device at a lower definition to+Sometimes, it is useful to mirror an Android device at a lower resolution toincrease performance.To limit both the width and height to some value (e.g. 1024):@@ -190,8 +190,8 @@ scrcpy --max-size 1024scrcpy -m 1024 # short version```-The other dimension is computed so that the device aspect ratio is preserved.-That way, a device in 1920×1080 will be mirrored at 1024×576.+The other dimension is computed so that the Android device aspect ratio is+preserved. That way, a device in 1920×1080 will be mirrored at 1024×576.#### Change bit-rate@@ -226,7 +226,7 @@ It may also be enabled or disabled at any time with <kbd>MOD</kbd>+<kbd>i</kbd>.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:+This is useful, for example, to mirror only one eye of the Oculus Go:```bashscrcpy --crop 1224:1440:0:0 # 1224x1440 at offset (0,0)@@ -237,7 +237,6 @@ If `--max-size` is also specified, resizing is applied after cropping.#### Lock video orientation-To lock the orientation of the mirroring:```bash@@ -262,7 +261,7 @@ 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+To list the available encoders, you can pass an invalid encoder name; theerror will give the available encoders:```bash@@ -326,7 +325,7 @@ v4l2-ctl --list-devicesls /dev/video*```-To start scrcpy using a v4l2 sink:+To start `scrcpy` using a v4l2 sink:```bashscrcpy --v4l2-sink=/dev/videoN@@ -334,7 +333,7 @@ scrcpy --v4l2-sink=/dev/videoN --no-display # disable mirroring windowscrcpy --v4l2-sink=/dev/videoN -N # short version```-(replace `N` by the device ID, check with `ls /dev/video*`)+(replace `N` with the device ID, check with `ls /dev/video*`)Once enabled, you can open your video stream with a v4l2-capable tool:@@ -350,7 +349,7 @@ For example, you could capture the video within [OBS].#### Buffering-It is possible to add buffering. This increases latency but reduces jitter (see+It is possible to add buffering. This increases latency, but reduces jitter (see[#2464]).[#2464]: https://github.com/Genymobile/scrcpy/issues/2464@@ -382,14 +381,14 @@ An option `--tcpip` allows to configure the connection automatically. There aretwo 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:+port (typically 5555) for incoming _adb_ connections, then run:```bashscrcpy --tcpip=192.168.1.1 # default port is 5555scrcpy --tcpip=192.168.1.1:5555```-If adb TCP/IP mode is disabled on the device (or if you don't know the IP+If _adb_ TCP/IP mode is disabled on the device (or if you don't know the IPaddress), connect the device over USB, then run:```bash@@ -413,7 +412,7 @@ Alternatively, it is possible to enable the TCP/IP connection manually usingadb shell ip route | awk '{print $9}'```-4. Enable adb over TCP/IP on your device: `adb tcpip 5555`.+4. Enable `adb` over TCP/IP on your device: `adb tcpip 5555`.5. Unplug your device.6. Connect to your device: `adb connect DEVICE_IP:5555` _(replace `DEVICE_IP`with the device IP address you found)_.@@ -427,9 +426,9 @@ having to physically connect your device directly to your computer.If the connection randomly drops, run your `scrcpy` command to reconnect. If itsays there are no devices/emulators found, try running `adb connectDEVICE_IP:5555` again, and then `scrcpy` as usual. If it still says there are-none found, try running `adb disconnect` and then run those two commands again.+none found, try running `adb disconnect`, and then run those two commands again.-It may be useful to decrease the bit-rate and the definition:+It may be useful to decrease the bit-rate and the resolution:```bashscrcpy --bit-rate 2M --max-size 800@@ -488,7 +487,7 @@ protocol).##### Remote ADB server-To connect to a remote ADB server, make the server listen on all interfaces:+To connect to a remote _adb server_, make the server listen on all interfaces:```bashadb kill-server@@ -496,17 +495,18 @@ adb -a nodaemon server start# keep this open```-**Warning: all communications between clients and ADB server are unencrypted.**+**Warning: all communications between clients and the _adb server_ are+unencrypted.**Suppose that this server is accessible at 192.168.1.2. Then, from another-terminal, run scrcpy:+terminal, run `scrcpy`:```bashexport ADB_SERVER_SOCKET=tcp:192.168.1.2:5037scrcpy --tunnel-host=192.168.1.2```-By default, scrcpy uses the local port used for `adb forward` tunnel+By default, `scrcpy` uses the local port used for `adb forward` tunnelestablishment (typically `27183`, see `--port`). It is also possible to force adifferent tunnel port (it may be useful in more complex situations, when moreredirections are involved):@@ -518,16 +518,16 @@ scrcpy --tunnel-port=1234##### SSH tunnel-To communicate with a remote ADB server securely, it is preferable to use a SSH-tunnel.+To communicate with a remote _adb server_ securely, it is preferable to use an+SSH tunnel.-First, make sure the ADB server is running on the remote computer:+First, make sure the _adb server_ is running on the remote computer:```bashadb start-server```-Then, establish a SSH tunnel:+Then, establish an SSH tunnel:```bash# local 5038 --> remote 5037@@ -536,7 +536,7 @@ ssh -CN -L5038:localhost:5037 -R27183:localhost:27183 your_remote_computer# keep this open```-From another terminal, run scrcpy:+From another terminal, run `scrcpy`:```bashexport ADB_SERVER_SOCKET=tcp:localhost:5038@@ -553,7 +553,7 @@ ssh -CN -L5038:localhost:5037 -L27183:localhost:27183 your_remote_computer# keep this open```-From another terminal, run scrcpy:+From another terminal, run `scrcpy`:```bashexport ADB_SERVER_SOCKET=tcp:localhost:5038@@ -595,7 +595,7 @@ scrcpy --window-borderless#### Always on top-To keep the scrcpy window always on top:+To keep the _scrcpy_ window always on top:```bashscrcpy --always-on-top@@ -620,7 +620,7 @@ The window may be rotated:scrcpy --rotation 1```-Possibles values are:+Possible values:- `0`: no rotation- `1`: 90 degrees counterclockwise- `2`: 180 degrees@@ -669,19 +669,19 @@ 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).+10 (otherwise it is mirrored as read-only).#### Stay awake-To prevent the device to sleep after some delay when the device is plugged in:+To prevent the device from sleeping after a delay when the device is plugged in:```bashscrcpy --stay-awakescrcpy -w```-The initial state is restored when scrcpy is closed.+The initial state is restored when _scrcpy_ is closed.#### Turn screen off@@ -699,9 +699,10 @@ Or by pressing <kbd>MOD</kbd>+<kbd>o</kbd> at any time.To turn it back on, press <kbd>MOD</kbd>+<kbd>Shift</kbd>+<kbd>o</kbd>.On Android, the `POWER` button always turns the screen on. For convenience, if-`POWER` is sent via scrcpy (via right-click or <kbd>MOD</kbd>+<kbd>p</kbd>), 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.+`POWER` is sent via _scrcpy_ (via right-click or <kbd>MOD</kbd>+<kbd>p</kbd>),+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:@@ -712,7 +713,7 @@ scrcpy -Sw#### Power off on close-To turn the device screen off when closing scrcpy:+To turn the device screen off when closing _scrcpy_:```bashscrcpy --power-off-on-close@@ -734,12 +735,13 @@ scrcpy --show-touchesscrcpy -t```-Note that it only shows _physical_ touches (with the finger on the device).+Note that it only shows _physical_ touches (by a finger on the device).#### Disable screensaver-By default, scrcpy does not prevent the screensaver to run on the computer.+By default, _scrcpy_ does not prevent the screensaver from running on the+computer.To disable it:@@ -781,18 +783,18 @@ To copy, cut and paste in such cases (but only supported on Android >= 7):- <kbd>MOD</kbd>+<kbd>v</kbd> injects `PASTE` (after computer-to-deviceclipboard synchronization)-In addition, <kbd>MOD</kbd>+<kbd>Shift</kbd>+<kbd>v</kbd> 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.+In addition, <kbd>MOD</kbd>+<kbd>Shift</kbd>+<kbd>v</kbd> injects 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<kbd>Ctrl</kbd>+<kbd>v</kbd> or <kbd>MOD</kbd>+<kbd>v</kbd>) copies the content-into the device clipboard. As a consequence, any Android application could read+into the Android clipboard. As a consequence, any Android application could readits content. You should avoid pasting sensitive content (like passwords) thatway.-Some devices do not behave as expected when setting the device clipboard+Some Android devices do not behave as expected when setting the device clipboardprogrammatically. An option `--legacy-paste` is provided to change the behaviorof <kbd>Ctrl</kbd>+<kbd>v</kbd> and <kbd>MOD</kbd>+<kbd>v</kbd> so that theyalso inject the computer clipboard text as a sequence of key events (the same@@ -805,29 +807,29 @@ To disable automatic clipboard synchronization, useTo simulate "pinch-to-zoom": <kbd>Ctrl</kbd>+_click-and-move_.-More precisely, hold <kbd>Ctrl</kbd> 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.+More precisely, hold down <kbd>Ctrl</kbd> 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.+Technically, _scrcpy_ generates additional touch events from a "virtual finger"+at a location inverted through the center of the screen.#### Physical keyboard simulation (HID)-By default, scrcpy uses Android key or text injection: it works everywhere, but-is limited to ASCII.+By default, _scrcpy_ uses Android key or text injection: it works everywhere,+but is limited to ASCII.-Alternatively, scrcpy can simulate a physical USB keyboard on Android to provide-a better input experience (using [USB HID over AOAv2][hid-aoav2]): the virtual-keyboard is disabled and it works for all characters and IME.+Alternatively, `scrcpy` can simulate a physical USB keyboard on Android to+provide a better input experience (using [USB HID over AOAv2][hid-aoav2]): the+virtual keyboard is disabled and it works for all characters and IME.[hid-aoav2]: https://source.android.com/devices/accessories/aoa2#hid-support-However, it only works if the device is connected by USB.+However, it only works if the device is connected via USB.Note: On Windows, it may only work in [OTG mode](#otg), not while mirroring (itis not possible to open a USB device if it is already open by another process-like the adb daemon).+like the _adb daemon_).To enable this mode:@@ -862,7 +864,7 @@ a physical keyboard is connected).Similarly to the physical keyboard simulation, it is possible to simulate aphysical mouse. Likewise, it only works if the device is connected by USB.-By default, scrcpy uses Android mouse events injection, using absolute+By default, _scrcpy_ uses Android mouse events injection with absolutecoordinates. By simulating a physical mouse, a mouse pointer appears on theAndroid device, and relative mouse motion, clicks and scrolls are injected.@@ -873,7 +875,7 @@ scrcpy --hid-mousescrcpy -M # short version```-You could also add `--forward-all-clicks` to [forward all mouse+You can also add `--forward-all-clicks` to [forward all mousebuttons][forward_all_clicks].[forward_all_clicks]: #right-click-and-middle-click@@ -892,7 +894,7 @@ It is possible to run _scrcpy_ with only physical keyboard and mouse simulation(HID), as if the computer keyboard and mouse were plugged directly to the devicevia an OTG cable.-In this mode, _adb_ (USB debugging) is not necessary, and mirroring is disabled.+In this mode, `adb` (USB debugging) is not necessary, and mirroring is disabled.To enable OTG mode:@@ -918,7 +920,7 @@ connected by USB.#### Text injection preference-There are two kinds of [events][textevents] generated when typing text:+Two kinds of [events][textevents] are generated when typing text:- _key events_, signaling that a key is pressed or released;- _text events_, signaling that a text has been entered.@@ -1075,7 +1077,7 @@ handled by the active application.## Custom paths-To use a specific _adb_ binary, configure its path in the environment variable+To use a specific `adb` binary, configure its path in the environment variable`ADB`:```bash@@ -1088,7 +1090,7 @@ To override the path of the `scrcpy-server` file, configure its path inTo override the icon, configure its path in `SCRCPY_ICON_PATH`.-## Why _scrcpy_?+## Why the name _scrcpy_?A colleague challenged me to find a name as unpronounceable as [gnirehtet].@@ -1148,7 +1150,7 @@ If you encounter a bug, please read the [FAQ] first, then open an [issue].[issue]: https://github.com/Genymobile/scrcpy/issues-For general questions or discussions, you could also use:+For general questions or discussions, you can also use:- Reddit: [`r/scrcpy`](https://www.reddit.com/r/scrcpy)- Twitter: [`@scrcpy_app`](https://twitter.com/scrcpy_app)