Skip to content

Display and control your Android device

Update README

Romain Vimont8ace3d178171
diff --git a/README.md b/README.md
index bfd3f2e7..2f429474 100644
--- a/README.md
+++ b/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_.
+![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.
diff --git a/assets/screenshot-debian-600.jpg b/assets/screenshot-debian-600.jpg
new file mode 100644
index 00000000..20000aa9
Binary files /dev/null and b/assets/screenshot-debian-600.jpg differ