Update README
Explain how to build, install and run the application.
This commit is contained in:
Romain Vimont
parent
bae8263cdd
commit
8ace3d1781
2 changed files with 152 additions and 91 deletions
243
README.md
243
README.md
|
|
@ -1,141 +1,202 @@
|
||||||
# ScrCpy
|
# scrcpy
|
||||||
|
|
||||||
This project displays screens of Android devices plugged on USB in live.
|
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_.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Run
|
## Requirements
|
||||||
|
|
||||||
### Runtime requirements
|
The Android part requires at least API 21 (Android 5.0).
|
||||||
|
|
||||||
This projects requires _FFmpeg_, _LibSDL2_ and _LibSDL2-net_.
|
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_.
|
||||||
|
|
||||||
|
|
||||||
|
## Build and install
|
||||||
|
|
||||||
|
### System-specific steps
|
||||||
|
|
||||||
#### Linux
|
#### Linux
|
||||||
|
|
||||||
Install the packages from your package manager. For example, on Debian:
|
Install the required packages from your package manager (here, for Debian):
|
||||||
|
|
||||||
sudo apt install ffmpeg libsdl2-2.0.0 libsdl2-net-2.0.0
|
# 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
|
||||||
|
|
||||||
|
|
||||||
#### Windows
|
#### Windows
|
||||||
|
|
||||||
From [MSYS2]:
|
For Windows, for simplicity, a prebuilt package with all the dependencies
|
||||||
|
(including `adb`) is available: TODO.
|
||||||
|
|
||||||
pacman -S mingw-w64-x86_64-SDL2
|
Instead, you may want to build it manually. You need [MSYS2] to build the
|
||||||
pacman -S mingw-w64-x86_64-SDL2_net
|
project. From an MSYS2 terminal, install the required packages:
|
||||||
pacman -S mingw-w64-x86_64-ffmpeg
|
|
||||||
|
|
||||||
[MSYS2]: http://www.msys2.org/
|
[MSYS2]: http://www.msys2.org/
|
||||||
|
|
||||||
|
# runtime dependencies
|
||||||
|
pacman -S mingw-w64-x86_64-SDL2 \
|
||||||
|
mingw-w64-x86_64-ffmpeg
|
||||||
|
|
||||||
#### MacOS
|
# 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
|
||||||
|
|
||||||
TODO
|
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`:
|
||||||
|
|
||||||
## Build
|
|
||||||
|
|
||||||
The project is divided into two parts:
|
|
||||||
- the server, running on the device (in `server/`);
|
|
||||||
- the client, running on the computer (in `app/`).
|
|
||||||
|
|
||||||
The server is a raw Java project requiring Android SDK. It not an Android
|
|
||||||
project: the target file is a `.jar`, and a `main()` method is executed with
|
|
||||||
_shell_ rights.
|
|
||||||
|
|
||||||
The client is a C project using [SDL] and [FFmpeg], built with [Meson]/[Ninja].
|
|
||||||
|
|
||||||
The root directory contains a `Makefile` to build both parts.
|
|
||||||
|
|
||||||
[sdl]: https://www.libsdl.org/
|
|
||||||
[ffmpeg]: https://www.ffmpeg.org/
|
|
||||||
[meson]: http://mesonbuild.com/
|
|
||||||
[ninja]: https://ninja-build.org/
|
|
||||||
|
|
||||||
|
|
||||||
### Build requirements
|
|
||||||
|
|
||||||
Install the [Android SDK], the JDK 8 (`openjdk-8-jdk`), and the packages
|
|
||||||
described below.
|
|
||||||
|
|
||||||
[Android SDK]: https://developer.android.com/studio/index.html
|
|
||||||
|
|
||||||
|
|
||||||
#### Linux
|
|
||||||
|
|
||||||
sudo apt install make gcc openjdk-8-jdk pkg-config meson zip \
|
|
||||||
libavcodec-dev libavformat-dev libavutil-dev \
|
|
||||||
libsdl2-dev libsdl2-net-dev
|
|
||||||
|
|
||||||
|
|
||||||
#### Windows
|
|
||||||
|
|
||||||
Install these packages:
|
|
||||||
|
|
||||||
pacman -S mingw-w64-x86_64-make
|
|
||||||
pacman -S mingw-w64-x86_64-gcc
|
|
||||||
pacman -S mingw-w64-x86_64-pkg-config
|
|
||||||
pacman -S mingw-w64-x86_64-meson
|
|
||||||
pacman -S zip
|
|
||||||
|
|
||||||
Java 8 is not available in MSYS2, so install it manually and make it available
|
|
||||||
from the `PATH`:
|
|
||||||
|
|
||||||
export PATH="$JAVA_HOME/bin:$PATH"
|
export PATH="$JAVA_HOME/bin:$PATH"
|
||||||
|
|
||||||
|
|
||||||
### Build
|
#### Mac OS
|
||||||
|
|
||||||
Make sure your `ANDROID_HOME` variable is set to your Android SDK directory:
|
Use [Homebrew] to install the packages:
|
||||||
|
|
||||||
|
[Homebrew]: https://brew.sh/
|
||||||
|
|
||||||
|
# runtime dependencies
|
||||||
|
brew install sdl2 ffmpeg
|
||||||
|
|
||||||
|
# build dependencies
|
||||||
|
brew install gcc pkg-config meson zip
|
||||||
|
|
||||||
|
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`:
|
||||||
|
|
||||||
|
export PATH="$JAVA_HOME/bin:$PATH"
|
||||||
|
|
||||||
|
|
||||||
|
### Common steps
|
||||||
|
|
||||||
|
Install the [Android SDK] (_Android Studio_), and set `ANDROID_HOME` to
|
||||||
|
its directory. For example:
|
||||||
|
|
||||||
|
[Android SDK]: https://developer.android.com/studio/index.html
|
||||||
|
|
||||||
export ANDROID_HOME=~/android/sdk
|
export ANDROID_HOME=~/android/sdk
|
||||||
|
|
||||||
From the project root directory, execute:
|
Then, build `scrcpy`:
|
||||||
|
|
||||||
make build
|
meson x --buildtype release --strip -Db_lto=true
|
||||||
|
cd x
|
||||||
|
ninja
|
||||||
|
|
||||||
To run the build:
|
You can test it from here:
|
||||||
|
|
||||||
make run
|
ninja run
|
||||||
|
|
||||||
It is also pass arguments to `scrcpy` via `make`:
|
Or you can install it on the system:
|
||||||
|
|
||||||
make run ARGS="-p 1234"
|
sudo ninja install # without sudo on Windows
|
||||||
|
|
||||||
The purpose of this command is to execute `scrcpy` during the development.
|
This installs two files:
|
||||||
|
|
||||||
|
- `/usr/local/bin/scrcpy`
|
||||||
|
- `/usr/local/share/scrcpy/scrcpy-server.jar`
|
||||||
|
|
||||||
|
Just remove them to "uninstall" the application.
|
||||||
|
|
||||||
|
|
||||||
### Test
|
#### Prebuilt server
|
||||||
|
|
||||||
To execute unit tests:
|
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).
|
||||||
|
|
||||||
make test
|
In that case, the build does not require Java or the Android SDK.
|
||||||
|
|
||||||
The server-side tests require JUnit 4:
|
Download the prebuilt server somewhere, and specify its path during the Meson
|
||||||
|
configuration:
|
||||||
|
|
||||||
sudo apt install junit4
|
meson x --buildtype release --strip -Db_lto=true \
|
||||||
|
-Dprebuilt_server=/path/to/scrcpy-server.jar
|
||||||
|
cd x
|
||||||
### Generate a release
|
ninja
|
||||||
|
sudo ninja install
|
||||||
From the project root directory, execute:
|
|
||||||
|
|
||||||
make release
|
|
||||||
|
|
||||||
This will generate the application in `dist/scrcpy/`.
|
|
||||||
|
|
||||||
|
|
||||||
## Run
|
## Run
|
||||||
|
|
||||||
Plug a device, and from `dist/scrcpy/`, execute:
|
_At runtime, `adb` must be accessible from your `PATH`._
|
||||||
|
|
||||||
./scrcpy
|
If everything is ok, just plug an Android device, and execute:
|
||||||
|
|
||||||
|
scrcpy
|
||||||
|
|
||||||
|
It accepts command-line arguments, listed by:
|
||||||
|
|
||||||
|
scrcpy --help
|
||||||
|
|
||||||
|
For example, to increase video bitrate to 8Mbps (default is 4Mbps):
|
||||||
|
|
||||||
|
scrcpy -b 8M
|
||||||
|
|
||||||
|
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):
|
||||||
|
|
||||||
|
scrcpy -m 1024
|
||||||
|
|
||||||
If several devices are listed in `adb devices`, you must specify the _serial_:
|
If several devices are listed in `adb devices`, you must specify the _serial_:
|
||||||
|
|
||||||
./scrcpy 0123456789abcdef
|
scrcpy -s 0123456789abcdef
|
||||||
|
|
||||||
To change the default port (useful to launch several `scrcpy` simultaneously):
|
|
||||||
|
|
||||||
./scrcpy -p 1234
|
## Shortcuts
|
||||||
|
|
||||||
Other options are available, check `scrcpy --help`.
|
| 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` |
|
||||||
|
|
||||||
|
|
||||||
|
## Licence
|
||||||
|
|
||||||
|
Copyright (C) 2018 Genymobile
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
|
||||||
BIN
assets/screenshot-debian-600.jpg
Normal file
BIN
assets/screenshot-debian-600.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
Loading…
Reference in a new issue