Archives
/
scrcpy
mirror of https://github.com/Genymobile/scrcpy
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update README

Browse Source 
Explain how to build, install and run the application.
pull/28/head
Romain Vimont 6 years ago
parent bae8263cdd
commit 8ace3d1781
2 changed files with 132 additions and 71 deletions
Show Stats Download Patch File Download Diff File

203
README.md
Unescape Escape View File

@ -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_.
![screenshot](assets/screenshot-debian-600.jpg)
## Run
### Runtime requirements
## 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_.
This projects requires _FFmpeg_, _LibSDL2_ and _LibSDL2-net_.
## Build and install
### System-specific steps
#### 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
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
pacman -S mingw-w64-x86_64-SDL2_net
pacman -S mingw-w64-x86_64-ffmpeg
Instead, you may want to build it manually. You need [MSYS2] to build the
project. From an MSYS2 terminal, install the required packages:
[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`:
export PATH="$JAVA_HOME/bin:$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/`).
#### Mac OS
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.
Use [Homebrew] to install the packages:
The client is a C project using [SDL] and [FFmpeg], built with [Meson]/[Ninja].
[Homebrew]: https://brew.sh/
The root directory contains a `Makefile` to build both parts.
# runtime dependencies
brew install sdl2 ffmpeg
[sdl]: https://www.libsdl.org/
[ffmpeg]: https://www.ffmpeg.org/
[meson]: http://mesonbuild.com/
[ninja]: https://ninja-build.org/
# 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`:
### Build requirements
export PATH="$JAVA_HOME/bin:$PATH"
Install the [Android SDK], the JDK 8 (`openjdk-8-jdk`), and the packages
described below.
[Android SDK]: https://developer.android.com/studio/index.html
### Common steps
Install the [Android SDK] (_Android Studio_), and set `ANDROID_HOME` to
its directory. For example:
#### Linux
[Android SDK]: https://developer.android.com/studio/index.html
sudo apt install make gcc openjdk-8-jdk pkg-config meson zip \
libavcodec-dev libavformat-dev libavutil-dev \
libsdl2-dev libsdl2-net-dev
export ANDROID_HOME=~/android/sdk
Then, build `scrcpy`:
#### Windows
meson x --buildtype release --strip -Db_lto=true
cd x
ninja
Install these packages:
You can test it from here:
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
ninja run
Java 8 is not available in MSYS2, so install it manually and make it available
from the `PATH`:
Or you can install it on the system:
export PATH="$JAVA_HOME/bin:$PATH"
sudo ninja install # without sudo on Windows
This installs two files:
### Build
- `/usr/local/bin/scrcpy`
- `/usr/local/share/scrcpy/scrcpy-server.jar`
Make sure your `ANDROID_HOME` variable is set to your Android SDK directory:
Just remove them to "uninstall" the application.
export ANDROID_HOME=~/android/sdk
From the project root directory, execute:
#### Prebuilt server
make build
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).
To run the build:
In that case, the build does not require Java or the Android SDK.
make run
Download the prebuilt server somewhere, and specify its path during the Meson
configuration:
It is also pass arguments to `scrcpy` via `make`:
meson x --buildtype release --strip -Db_lto=true \
-Dprebuilt_server=/path/to/scrcpy-server.jar
cd x
ninja
sudo ninja install
make run ARGS="-p 1234"
The purpose of this command is to execute `scrcpy` during the development.
## Run
_At runtime, `adb` must be accessible from your `PATH`._
### Test
If everything is ok, just plug an Android device, and execute:
To execute unit tests:
scrcpy
make test
It accepts command-line arguments, listed by:
The server-side tests require JUnit 4:
scrcpy --help
sudo apt install junit4
For example, to increase video bitrate to 8Mbps (default is 4Mbps):
scrcpy -b 8M
### Generate a release
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):
From the project root directory, execute:
scrcpy -m 1024
make release
If several devices are listed in `adb devices`, you must specify the _serial_:
This will generate the application in `dist/scrcpy/`.
scrcpy -s 0123456789abcdef
## Run
## Shortcuts
Plug a device, and from `dist/scrcpy/`, execute:
| 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` |
./scrcpy
If several devices are listed in `adb devices`, you must specify the _serial_:
## Licence
./scrcpy 0123456789abcdef
Copyright (C) 2018 Genymobile
To change the default port (useful to launch several `scrcpy` simultaneously):
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
./scrcpy -p 1234
http://www.apache.org/licenses/LICENSE-2.0
Other options are available, check `scrcpy --help`.
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
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

Write Preview
Loading…
Cancel
Save