diff --git a/README_zh.md b/README_zh.md new file mode 100644 index 00000000..adf1faab --- /dev/null +++ b/README_zh.md @@ -0,0 +1,754 @@ +# scrcpy (v1.16) + +本应用程序可以让你实现在电脑上对安卓设备的查看和操作。 +该程序不要求 _root_ 权限,它只需要您的手机和电脑通过USB(或通过TCP/IP)连接。 +该应用程序可以在 _GNU/Linux_, _Windows_ and _macOS_ 环境下运行 + +![screenshot](assets/screenshot-debian-600.jpg) + +它专注于: + + - **轻量** (原生,仅显示设备屏幕) + - **性能** (30~60fps) + - **质量** (分辨率可达1920x1080或更高) + - **低延迟** (35-70ms) + - **快速启动** (数秒内即能开始显示) + - **无侵入性** (不需要在安卓设备上安装任何程序) + + +## 使用要求 + +安卓设备系统版本需要在Android 5.0(API 21)或以上。 + +确保您在设备上开启了[adb调试]。 + +[adb调试]: https://developer.android.com/studio/command-line/adb.html#Enabling + +在某些设备上,你还需要开启[额外的选项]以用鼠标和键盘进行控制。 + +[额外的选项]: https://github.com/Genymobile/scrcpy/issues/70#issuecomment-373286323 + + +## 获取应用程序 + +Packaging status + +### Linux + +在Debian (_testing_ and _sid_ for now) 和Ubuntu (20.04)上: + +``` +apt install scrcpy +``` + +[Snap]包也是可用的: [`scrcpy`][snap-link]. + +[snap-link]: https://snapstats.org/snaps/scrcpy + +[snap]: https://en.wikipedia.org/wiki/Snappy_(package_manager) + +对于Fedora用户,我们提供[COPR]包: [`scrcpy`][copr-link]. + +[COPR]: https://fedoraproject.org/wiki/Category:Copr +[copr-link]: https://copr.fedorainfracloud.org/coprs/zeno/scrcpy/ + +对于Arch Linux用户,我们提供[AUR]包: [`scrcpy`][aur-link]. + +[AUR]: https://wiki.archlinux.org/index.php/Arch_User_Repository +[aur-link]: https://aur.archlinux.org/packages/scrcpy/ + +对于Gentoo用户,我们提供[Ebuild]包:[`scrcpy/`][ebuild-link]. + +[Ebuild]: https://wiki.gentoo.org/wiki/Ebuild +[ebuild-link]: https://github.com/maggu2810/maggu2810-overlay/tree/master/app-mobilephone/scrcpy + +您也可以[自行编译][BUILD](不必担心,这并不困难)。 + + + +### Windows + +在Windows上,简便起见,我们准备了包含所有依赖项(包括adb)的程序。 + + - [`scrcpy-win64-v1.16.zip`][direct-win64] + _(SHA-256: 3f30dc5db1a2f95c2b40a0f5de91ec1642d9f53799250a8c529bc882bc0918f0)_ + +[direct-win64]: https://github.com/Genymobile/scrcpy/releases/download/v1.16/scrcpy-win64-v1.16.zip + +您也可以在[Chocolatey]下载: + +[Chocolatey]: https://chocolatey.org/ + +```bash +choco install scrcpy +choco install adb # 如果你没有adb +``` + +也可以使用 [Scoop]: + +```bash +scoop install scrcpy +scoop install adb # 如果你没有adb +``` + +[Scoop]: https://scoop.sh + +您也可以[自行编译][BUILD]。 + + +### macOS + +本应用程序可以使用[Homebrew]下载。直接安装就可以了: + +[Homebrew]: https://brew.sh/ + +```bash +brew install scrcpy +``` + +您需要 `adb`,并且它应该可以通过 `PATH`被访问。如果您没有: + +```bash +brew cask install android-platform-tools +``` + +您也可以[自行编译][BUILD]。 + + +## 运行程序 + +用USB链接电脑和安卓设备,并执行: + +```bash +scrcpy +``` + +本程序接受命令行输入,可以通过如下命令查看帮助: + +```bash +scrcpy --help +``` + +## 功能介绍 + +### 画面设置 + +#### 缩小分辨率 + +有时候,将设备输出分辨率降低可以有效地提升性能。 + +我们可以将高度和宽度都限制在一定大小内(如 1024): + +```bash +scrcpy --max-size 1024 +scrcpy -m 1024 # short version +``` + +The other dimension is computed to that the device aspect ratio is preserved. +That way, a device in 1920×1080 will be mirrored at 1024×576. + + +#### 修改画面比特率 + +The default bit-rate is 8 Mbps. To change the video bitrate (e.g. to 2 Mbps): + +```bash +scrcpy --bit-rate 2M +scrcpy -b 2M # short version +``` + +#### Limit frame rate + +The capture frame rate can be limited: + +```bash +scrcpy --max-fps 15 +``` + +This is officially supported since Android 10, but may work on earlier versions. + +#### Crop + +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: + +```bash +scrcpy --crop 1224:1440:0:0 # 1224x1440 at offset (0,0) +``` + +If `--max-size` is also specified, resizing is applied after cropping. + + +#### Lock video orientation + + +To lock the orientation of the mirroring: + +```bash +scrcpy --lock-video-orientation 0 # natural orientation +scrcpy --lock-video-orientation 1 # 90° counterclockwise +scrcpy --lock-video-orientation 2 # 180° +scrcpy --lock-video-orientation 3 # 90° clockwise +``` + +This affects recording orientation. + + +### Recording + +It is possible to record the screen while mirroring: + +```bash +scrcpy --record file.mp4 +scrcpy -r file.mkv +``` + +To disable mirroring while recording: + +```bash +scrcpy --no-display --record file.mp4 +scrcpy -Nr file.mkv +# interrupt recording with Ctrl+C +``` + +"Skipped frames" are recorded, even if they are not displayed in real time (for +performance reasons). Frames are _timestamped_ on the device, so [packet delay +variation] does not impact the recorded file. + +[packet delay variation]: https://en.wikipedia.org/wiki/Packet_delay_variation + + +### Connection + +#### Wireless + +_Scrcpy_ uses `adb` to communicate with the device, and `adb` can [connect] to a +device over TCP/IP: + +1. Connect the device to the same Wi-Fi as your computer. +2. Get your device IP address (in Settings → About phone → Status). +3. Enable adb over TCP/IP on your device: `adb tcpip 5555`. +4. Unplug your device. +5. Connect to your device: `adb connect DEVICE_IP:5555` _(replace `DEVICE_IP`)_. +6. Run `scrcpy` as usual. + +It may be useful to decrease the bit-rate and the definition: + +```bash +scrcpy --bit-rate 2M --max-size 800 +scrcpy -b2M -m800 # short version +``` + +[connect]: https://developer.android.com/studio/command-line/adb.html#wireless + + +#### Multi-devices + +If several devices are listed in `adb devices`, you must specify the _serial_: + +```bash +scrcpy --serial 0123456789abcdef +scrcpy -s 0123456789abcdef # short version +``` + +If the device is connected over TCP/IP: + +```bash +scrcpy --serial 192.168.0.1:5555 +scrcpy -s 192.168.0.1:5555 # short version +``` + +You can start several instances of _scrcpy_ for several devices. + +#### Autostart on device connection + +You could use [AutoAdb]: + +```bash +autoadb scrcpy -s '{}' +``` + +[AutoAdb]: https://github.com/rom1v/autoadb + +#### SSH tunnel + +To connect to a remote device, it is possible to connect a local `adb` client to +a remote `adb` server (provided they use the same version of the _adb_ +protocol): + +```bash +adb kill-server # kill the local adb server on 5037 +ssh -CN -L5037:localhost:5037 -R27183:localhost:27183 your_remote_computer +# keep this open +``` + +From another terminal: + +```bash +scrcpy +``` + +To avoid enabling remote port forwarding, you could force a forward connection +instead (notice the `-L` instead of `-R`): + +```bash +adb kill-server # kill the local adb server on 5037 +ssh -CN -L5037:localhost:5037 -L27183:localhost:27183 your_remote_computer +# keep this open +``` + +From another terminal: + +```bash +scrcpy --force-adb-forward +``` + + +Like for wireless connections, it may be useful to reduce quality: + +``` +scrcpy -b2M -m800 --max-fps 15 +``` + +### Window configuration + +#### Title + +By default, the window title is the device model. It can be changed: + +```bash +scrcpy --window-title 'My device' +``` + +#### Position and size + +The initial window position and size may be specified: + +```bash +scrcpy --window-x 100 --window-y 100 --window-width 800 --window-height 600 +``` + +#### Borderless + +To disable window decorations: + +```bash +scrcpy --window-borderless +``` + +#### Always on top + +To keep the scrcpy window always on top: + +```bash +scrcpy --always-on-top +``` + +#### Fullscreen + +The app may be started directly in fullscreen: + +```bash +scrcpy --fullscreen +scrcpy -f # short version +``` + +Fullscreen can then be toggled dynamically with MOD+f. + +#### Rotation + +The window may be rotated: + +```bash +scrcpy --rotation 1 +``` + +Possibles values are: + - `0`: no rotation + - `1`: 90 degrees counterclockwise + - `2`: 180 degrees + - `3`: 90 degrees clockwise + +The rotation can also be changed dynamically with MOD+ +_(left)_ and MOD+ _(right)_. + +Note that _scrcpy_ manages 3 different rotations: +- MOD+r requests the device to switch between portrait and + landscape (the current running app may refuse, if it does support the + requested orientation). + - `--lock-video-orientation` changes the mirroring orientation (the orientation + of the video sent from the device to the computer). This affects the + recording. + - `--rotation` (or MOD+/MOD+) + rotates only the window content. This affects only the display, not the + recording. + + +### Other mirroring options + +#### Read-only + +To disable controls (everything which can interact with the device: input keys, +mouse events, drag&drop files): + +```bash +scrcpy --no-control +scrcpy -n +``` + +#### Display + +If several displays are available, it is possible to select the display to +mirror: + +```bash +scrcpy --display 1 +``` + +The list of display ids can be retrieved by: + +``` +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). + + +#### Stay awake + +To prevent the device to sleep after some delay when the device is plugged in: + +```bash +scrcpy --stay-awake +scrcpy -w +``` + +The initial state is restored when scrcpy is closed. + + +#### Turn screen off + +It is possible to turn the device screen off while mirroring on start with a +command-line option: + +```bash +scrcpy --turn-screen-off +scrcpy -S +``` + +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. + +It can also be useful to prevent the device from sleeping: + +```bash +scrcpy --turn-screen-off --stay-awake +scrcpy -Sw +``` + + +#### Render expired frames + +By default, to minimize latency, _scrcpy_ always renders the last decoded frame +available, and drops any previous one. + +To force the rendering of all frames (at a cost of a possible increased +latency), use: + +```bash +scrcpy --render-expired-frames +``` + +#### Show touches + +For presentations, it may be useful to show physical touches (on the physical +device). + +Android provides this feature in _Developers options_. + +_Scrcpy_ provides an option to enable this feature on start and restore the +initial value on exit: + +```bash +scrcpy --show-touches +scrcpy -t +``` + +Note that it only shows _physical_ touches (with the finger on the device). + + +#### Disable screensaver + +By default, scrcpy does not prevent the screensaver to run on the computer. + +To disable it: + +```bash +scrcpy --disable-screensaver +``` + + +### Input control + +#### Rotate device screen + +Press MOD+r to switch between portrait and landscape +modes. + +Note that it rotates only if the application in foreground supports the +requested orientation. + +#### Copy-paste + +Any time the Android clipboard changes, it is automatically synchronized to the +computer clipboard. + +Any Ctrl shortcut is forwarded to the device. In particular: + - Ctrl+c typically copies + - Ctrl+x typically cuts + - Ctrl+v typically pastes (after computer-to-device + clipboard synchronization) + +This typically works as you expect. + +The actual behavior depends on the active application though. For example, +_Termux_ sends SIGINT on Ctrl+c instead, and _K-9 Mail_ +composes a new message. + +To copy, cut and paste in such cases (but only supported on Android >= 7): + - MOD+c injects `COPY` + - MOD+x injects `CUT` + - 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. + +**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 +its content. You should avoid to paste sensitive content (like passwords) that +way. + + +#### Pinch-to-zoom + +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. + + +#### Text injection preference + +There are two kinds of [events][textevents] generated when typing text: + - _key events_, signaling that a key is pressed or released; + - _text events_, signaling that a text has been entered. + +By default, letters are injected using key events, so that the keyboard behaves +as expected in games (typically for WASD keys). + +But this may [cause issues][prefertext]. If you encounter such a problem, you +can avoid it by: + +```bash +scrcpy --prefer-text +``` + +(but this will break keyboard behavior in games) + +[textevents]: https://blog.rom1v.com/2018/03/introducing-scrcpy/#handle-text-input +[prefertext]: https://github.com/Genymobile/scrcpy/issues/650#issuecomment-512945343 + + +#### Key repeat + +By default, holding a key down generates repeated key events. This can cause +performance problems in some games, where these events are useless anyway. + +To avoid forwarding repeated key events: + +```bash +scrcpy --no-key-repeat +``` + + +### File drop + +#### Install APK + +To install an APK, drag & drop an APK file (ending with `.apk`) to the _scrcpy_ +window. + +There is no visual feedback, a log is printed to the console. + + +#### Push file to device + +To push a file to `/sdcard/` on the device, drag & drop a (non-APK) file to the +_scrcpy_ window. + +There is no visual feedback, a log is printed to the console. + +The target directory can be changed on start: + +```bash +scrcpy --push-target /sdcard/foo/bar/ +``` + + +### Audio forwarding + +Audio is not forwarded by _scrcpy_. Use [sndcpy]. + +Also see [issue #14]. + +[sndcpy]: https://github.com/rom1v/sndcpy +[issue #14]: https://github.com/Genymobile/scrcpy/issues/14 + + +## Shortcuts + +In the following list, MOD is the shortcut modifier. By default, it's +(left) Alt or (left) Super. + +It can be changed using `--shortcut-mod`. Possible keys are `lctrl`, `rctrl`, +`lalt`, `ralt`, `lsuper` and `rsuper`. For example: + +```bash +# use RCtrl for shortcuts +scrcpy --shortcut-mod=rctrl + +# use either LCtrl+LAlt or LSuper for shortcuts +scrcpy --shortcut-mod=lctrl+lalt,lsuper +``` + +_[Super] is typically the Windows or Cmd key._ + +[Super]: https://en.wikipedia.org/wiki/Super_key_(keyboard_button) + + | Action | Shortcut + | ------------------------------------------- |:----------------------------- + | Switch fullscreen mode | MOD+f + | Rotate display left | MOD+ _(left)_ + | Rotate display right | MOD+ _(right)_ + | Resize window to 1:1 (pixel-perfect) | MOD+g + | Resize window to remove black borders | MOD+w \| _Double-click¹_ + | Click on `HOME` | MOD+h \| _Middle-click_ + | Click on `BACK` | MOD+b \| _Right-click²_ + | Click on `APP_SWITCH` | MOD+s + | Click on `MENU` (unlock screen) | MOD+m + | Click on `VOLUME_UP` | MOD+ _(up)_ + | Click on `VOLUME_DOWN` | MOD+ _(down)_ + | Click on `POWER` | MOD+p + | Power on | _Right-click²_ + | Turn device screen off (keep mirroring) | MOD+o + | Turn device screen on | MOD+Shift+o + | Rotate device screen | MOD+r + | Expand notification panel | MOD+n + | Collapse notification panel | MOD+Shift+n + | Copy to clipboard³ | MOD+c + | Cut to clipboard³ | MOD+x + | Synchronize clipboards and paste³ | MOD+v + | Inject computer clipboard text | MOD+Shift+v + | Enable/disable FPS counter (on stdout) | MOD+i + | Pinch-to-zoom | Ctrl+_click-and-move_ + +_¹Double-click on black borders to remove them._ +_²Right-click turns the screen on if it was off, presses BACK otherwise._ +_³Only on Android >= 7._ + +All Ctrl+_key_ shortcuts are forwarded to the device, so they are +handled by the active application. + + +## Custom paths + +To use a specific _adb_ binary, configure its path in the environment variable +`ADB`: + + ADB=/path/to/adb scrcpy + +To override the path of the `scrcpy-server` file, configure its path in +`SCRCPY_SERVER_PATH`. + +[useful]: https://github.com/Genymobile/scrcpy/issues/278#issuecomment-429330345 + + +## Why _scrcpy_? + +A colleague challenged me to find a name as unpronounceable as [gnirehtet]. + +[`strcpy`] copies a **str**ing; `scrcpy` copies a **scr**een. + +[gnirehtet]: https://github.com/Genymobile/gnirehtet +[`strcpy`]: http://man7.org/linux/man-pages/man3/strcpy.3.html + + +## How to build? + +See [BUILD]. + +[BUILD]: BUILD.md + + +## Common issues + +See the [FAQ](FAQ.md). + + +## Developers + +Read the [developers page]. + +[developers page]: DEVELOP.md + + +## Licence + + Copyright (C) 2018 Genymobile + Copyright (C) 2018-2020 Romain Vimont + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +## Articles + +- [Introducing scrcpy][article-intro] +- [Scrcpy now works wirelessly][article-tcpip] + +[article-intro]: https://blog.rom1v.com/2018/03/introducing-scrcpy/ +[article-tcpip]: https://www.genymotion.com/blog/open-source-project-scrcpy-now-works-wirelessly/ + +## Translations + +This README is available in other languages: + +- [繁體中文 (Traditional Chinese, `zh-Hant`) - v1.15](README.zh-Hant.md) +- [한국어 (Korean, `ko`) - v1.11](README.ko.md) +- [português brasileiro (Brazilian Portuguese, `pt-BR`) - v1.12.1](README.pt-br.md) + +Only this README file is guaranteed to be up-to-date.