2018-02-14 02:31:44 +08:00
|
|
|
|
# scrcpy
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
This project displays screens of Android devices connected on USB, and allow to
|
|
|
|
|
control them using the host mouse and keyboard. It does not require any _root_
|
|
|
|
|
access. It works on _GNU/Linux_, _Windows_ and _Mac OS_.
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
![screenshot](assets/screenshot-debian-600.jpg)
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
|
|
|
|
|
2018-02-14 02:31:44 +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
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
|
|
|
|
|
## Build and install
|
|
|
|
|
|
|
|
|
|
### System-specific steps
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
|
|
|
|
#### Linux
|
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
Install the required packages from your package manager (here, for Debian):
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
# runtime dependencies
|
|
|
|
|
sudo apt install ffmpeg libsdl2-2.0.0
|
|
|
|
|
|
|
|
|
|
# build dependencies
|
|
|
|
|
sudo apt install make gcc openjdk-8-jdk pkg-config meson zip \
|
|
|
|
|
libavcodec-dev libavformat-dev libavutil-dev \
|
|
|
|
|
libsdl2-dev
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### Windows
|
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
For Windows, for simplicity, a prebuilt package with all the dependencies
|
|
|
|
|
(including `adb`) is available: TODO.
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +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/
|
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
# runtime dependencies
|
|
|
|
|
pacman -S mingw-w64-x86_64-SDL2 \
|
|
|
|
|
mingw-w64-x86_64-ffmpeg
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
# 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 \
|
|
|
|
|
zip
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
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`:
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
export PATH="$JAVA_HOME/bin:$PATH"
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
#### Mac OS
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
Use [Homebrew] to install the packages:
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
[Homebrew]: https://brew.sh/
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
# runtime dependencies
|
|
|
|
|
brew install sdl2 ffmpeg
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
# build dependencies
|
|
|
|
|
brew install gcc pkg-config meson zip
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
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`:
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
export PATH="$JAVA_HOME/bin:$PATH"
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
### Common steps
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +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
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
[Android SDK]: https://developer.android.com/studio/index.html
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
export ANDROID_HOME=~/android/sdk
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
Then, build `scrcpy`:
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
meson x --buildtype release --strip -Db_lto=true
|
|
|
|
|
cd x
|
|
|
|
|
ninja
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
You can test it from here:
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
ninja run
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
Or you can install it on the system:
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
sudo ninja install # without sudo on Windows
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
This installs two files:
|
2018-01-19 00:24:38 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
- `/usr/local/bin/scrcpy`
|
|
|
|
|
- `/usr/local/share/scrcpy/scrcpy-server.jar`
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
Just remove them to "uninstall" the application.
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
#### Prebuilt server
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +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: [`scrcpy-server.jar`](TODO).
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
In that case, the build does not require Java or the Android SDK.
|
2018-02-04 19:17:34 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
Download the prebuilt server somewhere, and specify its path during the Meson
|
|
|
|
|
configuration:
|
2018-02-04 19:17:34 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
meson x --buildtype release --strip -Db_lto=true \
|
|
|
|
|
-Dprebuilt_server=/path/to/scrcpy-server.jar
|
|
|
|
|
cd x
|
|
|
|
|
ninja
|
|
|
|
|
sudo ninja install
|
2018-02-04 19:17:34 +08:00
|
|
|
|
|
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
## Run
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
_At runtime, `adb` must be accessible from your `PATH`._
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
If everything is ok, just plug an Android device, and execute:
|
2018-01-19 00:24:38 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
scrcpy
|
2018-01-19 00:24:38 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
It accepts command-line arguments, listed by:
|
2018-01-19 00:24:38 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
scrcpy --help
|
2018-01-19 00:24:38 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
For example, to increase video bitrate to 8Mbps (default is 4Mbps):
|
2018-01-19 00:24:38 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
scrcpy -b 8M
|
2018-01-19 00:24:38 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
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):
|
2018-02-04 19:17:34 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
scrcpy -m 1024
|
2018-02-04 19:17:34 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
If several devices are listed in `adb devices`, you must specify the _serial_:
|
2018-02-04 19:17:34 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
scrcpy -s 0123456789abcdef
|
2018-02-04 19:17:34 +08:00
|
|
|
|
|
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
## Shortcuts
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +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` |
|
|
|
|
|
| click on `HOME` | `Ctrl`+`h` |
|
|
|
|
|
| click on `BACK` | `Ctrl`+`b` |
|
|
|
|
|
| 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_ |
|
|
|
|
|
| enable/disable FPS counter (on stdout) | `Ctrl`+`i` |
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
## Licence
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
Copyright (C) 2018 Genymobile
|
2017-12-12 22:54:33 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +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
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
2018-02-04 19:17:34 +08:00
|
|
|
|
|
2018-02-14 02:31:44 +08:00
|
|
|
|
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.
|