Improve README
Improve clarity, grammar, consistency, punctuation, and formatting. PR #3177 <https://github.com/Genymobile/scrcpy/pull/3177> Signed-off-by: Romain Vimont <rom@rom1v.com>
This commit is contained in:
parent
53b1e16f42
commit
3c8ebf9abd
1 changed files with 73 additions and 71 deletions
144
README.md
144
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 <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:
|
||||
|
||||
```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 <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_:
|
||||
|
||||
```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):
|
|||
- <kbd>MOD</kbd>+<kbd>v</kbd> injects `PASTE` (after computer-to-device
|
||||
clipboard 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 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 <kbd>Ctrl</kbd>+<kbd>v</kbd> and <kbd>MOD</kbd>+<kbd>v</kbd> 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": <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 (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)
|
||||
|
|
Loading…
Reference in a new issue