395 lines
10 KiB
Markdown
395 lines
10 KiB
Markdown
# scrcpy (v1.9)
|
||
|
||
This application provides display and control of Android devices connected on
|
||
USB (or [over TCP/IP][article-tcpip]). It does not require any _root_ access.
|
||
It works on _GNU/Linux_, _Windows_ and _macOS_.
|
||
|
||
|
||
|
||
|
||
## Requirements
|
||
|
||
The Android device requires at least API 21 (Android 5.0).
|
||
|
||
Make sure you [enabled 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]: https://github.com/Genymobile/scrcpy/issues/70#issuecomment-373286323
|
||
|
||
|
||
## Get the app
|
||
|
||
|
||
### Linux
|
||
|
||
On Linux, you typically need to [build the app manually][BUILD]. Don't worry,
|
||
it's not that hard.
|
||
|
||
A [Snap] package is available: [`scrcpy`][snap-link].
|
||
|
||
[snap-link]: https://snapstats.org/snaps/scrcpy
|
||
|
||
[snap]: https://en.wikipedia.org/wiki/Snappy_(package_manager)
|
||
|
||
For Arch Linux, an [AUR] package is available: [`scrcpy`][aur-link].
|
||
|
||
[AUR]: https://wiki.archlinux.org/index.php/Arch_User_Repository
|
||
[aur-link]: https://aur.archlinux.org/packages/scrcpy/
|
||
|
||
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
|
||
|
||
|
||
### Windows
|
||
|
||
For Windows, for simplicity, prebuilt archives with all the dependencies
|
||
(including `adb`) are available:
|
||
|
||
- [`scrcpy-win32-v1.9.zip`][direct-win32]
|
||
_(SHA-256: 3234f7fbcc26b9e399f50b5ca9ed085708954c87fda1b0dd32719d6e7dd861ef)_
|
||
- [`scrcpy-win64-v1.9.zip`][direct-win64]
|
||
_(SHA-256: 0088eca1811ea7c7ac350d636c8465b266e6c830bb268770ff88fddbb493077e)_
|
||
|
||
[direct-win32]: https://github.com/Genymobile/scrcpy/releases/download/v1.9/scrcpy-win32-v1.9.zip
|
||
[direct-win64]: https://github.com/Genymobile/scrcpy/releases/download/v1.9/scrcpy-win64-v1.9.zip
|
||
|
||
You can also [build the app manually][BUILD].
|
||
|
||
|
||
### macOS
|
||
|
||
The application is available in [Homebrew]. Just install it:
|
||
|
||
[Homebrew]: https://brew.sh/
|
||
|
||
```bash
|
||
brew install scrcpy
|
||
```
|
||
|
||
You need `adb`, accessible from your `PATH`. If you don't have it yet:
|
||
|
||
```bash
|
||
brew cask install android-platform-tools
|
||
```
|
||
|
||
You can also [build the app manually][BUILD].
|
||
|
||
|
||
## Run
|
||
|
||
Plug an Android device, and execute:
|
||
|
||
```bash
|
||
scrcpy
|
||
```
|
||
|
||
It accepts command-line arguments, listed by:
|
||
|
||
```bash
|
||
scrcpy --help
|
||
```
|
||
|
||
## Features
|
||
|
||
|
||
### Reduce size
|
||
|
||
Sometimes, it is useful to mirror an Android device at a lower definition to
|
||
increase performance.
|
||
|
||
To limit both the width and height to some value (e.g. 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.
|
||
|
||
|
||
### Change bit-rate
|
||
|
||
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
|
||
```
|
||
|
||
|
||
### 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)
|
||
scrcpy -c 1224:1440:0:0 # short version
|
||
```
|
||
|
||
If `--max-size` is also specified, resizing is applied after cropping.
|
||
|
||
|
||
### 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
|
||
|
||
|
||
### Record screen
|
||
|
||
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
|
||
# Ctrl+C does not terminate properly on Windows, so disconnect the device
|
||
```
|
||
|
||
"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
|
||
|
||
|
||
### Multi-devices
|
||
|
||
If several devices are listed in `adb devices`, you must specify the _serial_:
|
||
|
||
```bash
|
||
scrcpy --serial 0123456789abcdef
|
||
scrcpy -s 0123456789abcdef # short version
|
||
```
|
||
|
||
You can start several instances of _scrcpy_ for several devices.
|
||
|
||
|
||
### Fullscreen
|
||
|
||
The app may be started directly in fullscreen:
|
||
|
||
```bash
|
||
scrcpy --fullscreen
|
||
scrcpy -f # short version
|
||
```
|
||
|
||
Fullscreen can then be toggled dynamically with `Ctrl`+`f`.
|
||
|
||
|
||
### Always on top
|
||
|
||
The window of app can always be above others by:
|
||
|
||
```bash
|
||
scrcpy --always-on-top
|
||
scrcpy -T # short version
|
||
```
|
||
|
||
|
||
### 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 disable on exit:
|
||
|
||
```bash
|
||
scrcpy --show-touches
|
||
scrcpy -t
|
||
```
|
||
|
||
Note that it only shows _physical_ touches (with the finger on the device).
|
||
|
||
|
||
### 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.
|
||
|
||
|
||
### 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
|
||
```
|
||
|
||
### 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 `Ctrl`+`o` at any time.
|
||
|
||
To turn it back on, press `POWER` (or `Ctrl`+`p`).
|
||
|
||
|
||
### 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
|
||
```
|
||
|
||
|
||
### Forward audio
|
||
|
||
Audio is not forwarded by _scrcpy_. Use [USBaudio] (Linux-only).
|
||
|
||
Also see [issue #14].
|
||
|
||
[USBaudio]: https://github.com/rom1v/usbaudio
|
||
[issue #14]: https://github.com/Genymobile/scrcpy/issues/14
|
||
|
||
|
||
## Shortcuts
|
||
|
||
| Action | Shortcut |
|
||
| -------------------------------------- |:---------------------------- |
|
||
| Switch fullscreen mode | `Ctrl`+`f` |
|
||
| Resize window to 1:1 (pixel-perfect) | `Ctrl`+`g` |
|
||
| Resize window to remove black borders | `Ctrl`+`x` \| _Double-click¹_ |
|
||
| Click on `HOME` | `Ctrl`+`h` \| _Middle-click_ |
|
||
| Click on `BACK` | `Ctrl`+`b` \| _Right-click²_ |
|
||
| Click on `APP_SWITCH` | `Ctrl`+`s` |
|
||
| Click on `MENU` | `Ctrl`+`m` |
|
||
| Click on `VOLUME_UP` | `Ctrl`+`↑` _(up)_ (`Cmd`+`↑` on macOS) |
|
||
| Click on `VOLUME_DOWN` | `Ctrl`+`↓` _(down)_ (`Cmd`+`↓` on macOS) |
|
||
| Click on `POWER` | `Ctrl`+`p` |
|
||
| Power on | _Right-click²_ |
|
||
| Turn device screen off (keep mirroring)| `Ctrl`+`o` |
|
||
| Expand notification panel | `Ctrl`+`n` |
|
||
| Collapse notification panel | `Ctrl`+`Shift`+`n` |
|
||
| Copy device clipboard to computer | `Ctrl`+`c` |
|
||
| Paste computer clipboard to device | `Ctrl`+`v` |
|
||
| Copy computer clipboard to device | `Ctrl`+`Shift`+`v` |
|
||
| Enable/disable FPS counter (on stdout) | `Ctrl`+`i` |
|
||
|
||
_¹Double-click on black borders to remove them._
|
||
_²Right-click turns the screen on if it was off, presses BACK otherwise._
|
||
|
||
|
||
## 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.jar` 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-2019 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/
|