scrcpy/README.md

306 lines
7.9 KiB
Markdown
Raw Normal View History

# scrcpy
2017-12-12 22:54:33 +08:00
This application provides display and control of Android devices connected on
USB. It does not require any _root_ access. It works on _GNU/Linux_, _Windows_
and _MacOS_.
2017-12-12 22:54:33 +08:00
![screenshot](assets/screenshot-debian-600.jpg)
2017-12-12 22:54:33 +08:00
## Requirements
The Android part requires at least API 21 (Android 5.0).
You need [adb] (recent enough so that `adb reverse` is implemented, it works
with 1.0.36). It is available in the [Android SDK platform
tools][platform-tools], on packaged in your distribution (`android-adb-tools`).
On Windows, just download the [platform-tools][platform-tools-windows] and
extract the following files to a directory accessible from your `PATH`:
- `adb.exe`
- `AdbWinApi.dll`
- `AdbWinUsbApi.dll`
Make sure you [enabled adb debugging][enable-adb] on your device(s).
[adb]: https://developer.android.com/studio/command-line/adb.html
[enable-adb]: https://developer.android.com/studio/command-line/adb.html#Enabling
[platform-tools]: https://developer.android.com/studio/releases/platform-tools.html
[platform-tools-windows]: https://dl.google.com/android/repository/platform-tools-latest-windows.zip
The client requires _FFmpeg_ and _LibSDL2_.
2017-12-12 22:54:33 +08:00
## Build and install
### System-specific steps
2017-12-12 22:54:33 +08:00
#### Linux
Install the required packages from your package manager.
##### Debian/Ubuntu
```bash
# runtime dependencies
sudo apt install ffmpeg libsdl2-2.0.0
2017-12-12 22:54:33 +08:00
# client build dependencies
sudo apt install make gcc pkg-config meson \
libavcodec-dev libavformat-dev libavutil-dev \
libsdl2-dev
# server build dependencies
sudo apt install openjdk-8-jdk
```
2017-12-12 22:54:33 +08:00
##### Fedora
2018-03-12 00:20:58 +08:00
```bash
# enable RPM fusion free
sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
# client build dependencies
2018-03-12 00:20:58 +08:00
sudo dnf install SDL2-devel ffms2-devel meson gcc make
# server build dependencies
sudo dnf install java
2018-03-12 00:20:58 +08:00
```
2018-03-12 23:00:12 +08:00
##### Arch Linux
Two [AUR] packages have been created by users:
- [`scrcpy`](https://aur.archlinux.org/packages/scrcpy/)
- [`scrcpy-prebuiltserver`](https://aur.archlinux.org/packages/scrcpy-prebuiltserver/)
[AUR]: https://wiki.archlinux.org/index.php/Arch_User_Repository
2017-12-12 22:54:33 +08:00
#### Windows
For Windows, for simplicity, a prebuilt archive with all the dependencies
(including `adb`) is available:
2018-03-14 16:53:55 +08:00
- [`scrcpy-windows-with-deps-v1.1.zip`][direct-windows-with-deps].
_(SHA-256: 27eb36c15937601d1062c1dc0b45faae0e06fefea2019aadeb4fa7f76a07bb4c)_
2018-03-14 16:53:55 +08:00
[direct-windows-with-deps]: https://github.com/Genymobile/scrcpy/releases/download/v1.1/scrcpy-windows-with-deps-v1.1.zip
_(It's just a portable version including _dll_ copied from MSYS2.)_
2017-12-12 22:54:33 +08:00
Instead, you may want to build it manually. You need [MSYS2] to build the
project. From an MSYS2 terminal, install the required packages:
2017-12-12 22:54:33 +08:00
[MSYS2]: http://www.msys2.org/
```bash
# runtime dependencies
pacman -S mingw-w64-x86_64-SDL2 \
mingw-w64-x86_64-ffmpeg
# client build dependencies
pacman -S mingw-w64-x86_64-make \
mingw-w64-x86_64-gcc \
mingw-w64-x86_64-pkg-config \
mingw-w64-x86_64-meson
```
Java (>= 7) is not available in MSYS2, so if you plan to build the server,
install it manually and make it available from the `PATH`:
```bash
export PATH="$JAVA_HOME/bin:$PATH"
```
2017-12-12 22:54:33 +08:00
#### Mac OS
2017-12-12 22:54:33 +08:00
Use [Homebrew] to install the packages:
2017-12-12 22:54:33 +08:00
[Homebrew]: https://brew.sh/
```bash
# runtime dependencies
brew install sdl2 ffmpeg
2017-12-12 22:54:33 +08:00
# client build dependencies
brew install gcc pkg-config meson
```
Java (>= 7) is not available in Homebrew, so if you plan to build the server,
install it manually and make it available from the `PATH`:
```bash
export PATH="$JAVA_HOME/bin:$PATH"
```
2017-12-12 22:54:33 +08:00
### Common steps
2017-12-12 22:54:33 +08:00
Install the [Android SDK] (_Android Studio_), and set `ANDROID_HOME` to
its directory. For example:
2017-12-12 22:54:33 +08:00
[Android SDK]: https://developer.android.com/studio/index.html
```bash
export ANDROID_HOME=~/android/sdk
```
Then, build `scrcpy`:
```bash
meson x --buildtype release --strip -Db_lto=true
cd x
ninja
```
You can test it from here:
```bash
ninja run
```
Or you can install it on the system:
```bash
sudo ninja install # without sudo on Windows
```
This installs two files:
- `/usr/local/bin/scrcpy`
- `/usr/local/share/scrcpy/scrcpy-server.jar`
2017-12-12 22:54:33 +08:00
Just remove them to "uninstall" the application.
2017-12-12 22:54:33 +08:00
#### Prebuilt server
2017-12-12 22:54:33 +08:00
Since the server binary, that will be pushed to the Android device, does not
depend on your system and architecture, you may want to use the prebuilt binary
instead:
2018-03-14 16:53:55 +08:00
- [`scrcpy-server-v1.1.jar`][direct-scrcpy-server].
_(SHA-256: 14826512bf38447ec94adf3b531676ce038d19e7e06757fb4e537882b17e77b3)_
2018-03-14 16:53:55 +08:00
[direct-scrcpy-server]: https://github.com/Genymobile/scrcpy/releases/download/v1.1/scrcpy-server-v1.1.jar
2017-12-12 22:54:33 +08:00
In that case, the build does not require Java or the Android SDK.
Download the prebuilt server somewhere, and specify its path during the Meson
configuration:
```bash
meson x --buildtype release --strip -Db_lto=true \
-Dprebuilt_server=/path/to/scrcpy-server.jar
cd x
ninja
sudo ninja install
```
## Run
2017-12-12 22:54:33 +08:00
_At runtime, `adb` must be accessible from your `PATH`._
2017-12-12 22:54:33 +08:00
If everything is ok, just plug an Android device, and execute:
```bash
scrcpy
```
It accepts command-line arguments, listed by:
```bash
scrcpy --help
```
For example, to decrease video bitrate to 2Mbps (default is 8Mbps):
```bash
scrcpy -b 2M
```
To limit the video dimensions (e.g. if the device is 2540×1440, but the host
screen is smaller, or cannot decode such a high definition):
```bash
scrcpy -m 1024
```
If several devices are listed in `adb devices`, you must specify the _serial_:
```bash
scrcpy -s 0123456789abcdef
```
To run without installing:
```bash
./run x [options]
```
(where `x` is your build directory).
## Shortcuts
2017-12-12 22:54:33 +08:00
| 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`+`m` |
| click on `VOLUME_UP` | `Ctrl`+`+` |
| click on `VOLUME_DOWN` | `Ctrl`+`-` |
| click on `POWER` | `Ctrl`+`p` |
| turn screen on | _Right-click¹_ |
| paste computer clipboard to device | `Ctrl`+`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._
2017-12-12 22:54:33 +08:00
## 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
2018-03-11 17:34:11 +08:00
## Common issues
See the [FAQ](FAQ.md).
## Developers
Read the [developers page].
[developers page]: DEVELOP.md
## Licence
2017-12-12 22:54:33 +08:00
Copyright (C) 2018 Genymobile
2017-12-12 22:54:33 +08:00
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
2017-12-12 22:54:33 +08:00
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.
2018-03-08 19:31:26 +08:00
## Article
- [Introducing scrcpy](https://blog.rom1v.com/2018/03/introducing-scrcpy/)