From 3c8ebf9abd4410fd46485db43035e35b3780e8d4 Mon Sep 17 00:00:00 2001 From: Gitoffthelawn Date: Sun, 10 Apr 2022 08:45:34 -0700 Subject: [PATCH] Improve README Improve clarity, grammar, consistency, punctuation, and formatting. PR #3177 Signed-off-by: Romain Vimont --- README.md | 144 +++++++++++++++++++++++++++--------------------------- 1 file changed, 73 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index 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_. ![screenshot](assets/screenshot-debian-600.jpg) @@ -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#Enabling On 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] ([simplified process][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: ```bash sudo 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: ```bash scrcpy @@ -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 to increase performance. To limit both the width and height to some value (e.g. 1024): @@ -190,8 +190,8 @@ scrcpy --max-size 1024 scrcpy -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 MOD+i. 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: ```bash scrcpy --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; the error will give the available encoders: ```bash @@ -326,7 +325,7 @@ v4l2-ctl --list-devices ls /dev/video* ``` -To start scrcpy using a v4l2 sink: +To start `scrcpy` using a v4l2 sink: ```bash scrcpy --v4l2-sink=/dev/videoN @@ -334,7 +333,7 @@ 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*`) +(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 are 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: +port (typically 5555) for incoming _adb_ connections, then run: ```bash scrcpy --tcpip=192.168.1.1 # default port is 5555 scrcpy --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 IP address), connect the device over USB, then run: ```bash @@ -413,7 +412,7 @@ Alternatively, it is possible to enable the TCP/IP connection manually using adb 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 it says there are no devices/emulators found, try running `adb connect DEVICE_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: ```bash scrcpy --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: ```bash adb 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`: ```bash export ADB_SERVER_SOCKET=tcp:192.168.1.2:5037 scrcpy --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` tunnel establishment (typically `27183`, see `--port`). It is also possible to force a different tunnel port (it may be useful in more complex situations, when more redirections 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: ```bash adb 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`: ```bash export 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`: ```bash export 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: ```bash scrcpy --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: ```bash scrcpy --stay-awake scrcpy -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 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. +`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: @@ -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_: ```bash scrcpy --power-off-on-close @@ -734,12 +735,13 @@ scrcpy --show-touches scrcpy -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): - 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. +In addition, MOD+Shift+v 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 Ctrl+v or MOD+v) 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 read its content. You should avoid pasting sensitive content (like passwords) that way. -Some devices do not behave as expected when setting the device clipboard +Some Android 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 @@ -805,29 +807,29 @@ To disable automatic clipboard synchronization, use 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. +More precisely, hold down 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. +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 (it is 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 a physical 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 absolute coordinates. By simulating a physical mouse, a mouse pointer appears on the Android device, and relative mouse motion, clicks and scrolls are injected. @@ -873,7 +875,7 @@ scrcpy --hid-mouse scrcpy -M # short version ``` -You could also add `--forward-all-clicks` to [forward all mouse +You can also add `--forward-all-clicks` to [forward all mouse buttons][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 device via 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 in To 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)