Skip to content

Commit 8ace3d1

Browse files
rom1vrom1v
committed
Update README
Explain how to build, install and run the application.
1 parent bae8263 commit 8ace3d1

File tree

2 files changed

+132
-71
lines changed

2 files changed

+132
-71
lines changed

‎README.md

+132-71
Original file line numberDiff line numberDiff line change
@@ -1,141 +1,202 @@
1-
# ScrCpy
1+
# scrcpy
22

3-
This project displays screens of Android devices plugged on USB in live.
3+
This project displays screens of Android devices connected on USB, and allow to
4+
control them using the host mouse and keyboard. It does not require any _root_
5+
access. It works on _GNU/Linux_, _Windows_ and _Mac OS_.
46

7+
![screenshot](assets/screenshot-debian-600.jpg)
58

6-
## Run
79

8-
### Runtime requirements
10+
## Requirements
11+
12+
The Android part requires at least API 21 (Android 5.0).
13+
14+
You need [adb] (recent enough so that `adb reverse` is implemented, it works
15+
with 1.0.36). It is available in the [Android SDK platform
16+
tools][platform-tools], on packaged in your distribution (`android-adb-tools`).
17+
18+
On Windows, just download the [platform-tools][platform-tools-windows] and
19+
extract the following files to a directory accessible from your `PATH`:
20+
- `adb.exe`
21+
- `AdbWinApi.dll`
22+
- `AdbWinUsbApi.dll`
23+
24+
Make sure you [enabled adb debugging][enable-adb] on your device(s).
25+
26+
[adb]: https://developer.android.com/studio/command-line/adb.html
27+
[enable-adb]: https://developer.android.com/studio/command-line/adb.html#Enabling
28+
[platform-tools]: https://developer.android.com/studio/releases/platform-tools.html
29+
[platform-tools-windows]: https://dl.google.com/android/repository/platform-tools-latest-windows.zip
30+
31+
The client requires _FFmpeg_ and _LibSDL2_.
932

10-
This projects requires _FFmpeg_, _LibSDL2_ and _LibSDL2-net_.
33+
34+
## Build and install
35+
36+
### System-specific steps
1137

1238
#### Linux
1339

14-
Install the packages from your package manager. For example, on Debian:
40+
Install the required packages from your package manager (here, for Debian):
1541

16-
sudo apt install ffmpeg libsdl2-2.0.0 libsdl2-net-2.0.0
42+
# runtime dependencies
43+
sudo apt install ffmpeg libsdl2-2.0.0
44+
45+
# build dependencies
46+
sudo apt install make gcc openjdk-8-jdk pkg-config meson zip \
47+
libavcodec-dev libavformat-dev libavutil-dev \
48+
libsdl2-dev
1749

1850

1951
#### Windows
2052

21-
From [MSYS2]:
53+
For Windows, for simplicity, a prebuilt package with all the dependencies
54+
(including `adb`) is available: TODO.
2255

23-
pacman -S mingw-w64-x86_64-SDL2
24-
pacman -S mingw-w64-x86_64-SDL2_net
25-
pacman -S mingw-w64-x86_64-ffmpeg
56+
Instead, you may want to build it manually. You need [MSYS2] to build the
57+
project. From an MSYS2 terminal, install the required packages:
2658

2759
[MSYS2]: http://www.msys2.org/
2860

61+
# runtime dependencies
62+
pacman -S mingw-w64-x86_64-SDL2 \
63+
mingw-w64-x86_64-ffmpeg
2964

30-
#### MacOS
65+
# build dependencies
66+
pacman -S mingw-w64-x86_64-make \
67+
mingw-w64-x86_64-gcc \
68+
mingw-w64-x86_64-pkg-config \
69+
mingw-w64-x86_64-meson \
70+
zip
3171

32-
TODO
72+
Java (>= 7) is not available in MSYS2, so if you plan to build the server,
73+
install it manually and make it available from the `PATH`:
3374

75+
export PATH="$JAVA_HOME/bin:$PATH"
3476

35-
## Build
3677

37-
The project is divided into two parts:
38-
- the server, running on the device (in `server/`);
39-
- the client, running on the computer (in `app/`).
78+
#### Mac OS
4079

41-
The server is a raw Java project requiring Android SDK. It not an Android
42-
project: the target file is a `.jar`, and a `main()` method is executed with
43-
_shell_ rights.
80+
Use [Homebrew] to install the packages:
4481

45-
The client is a C project using [SDL] and [FFmpeg], built with [Meson]/[Ninja].
82+
[Homebrew]: https://brew.sh/
4683

47-
The root directory contains a `Makefile` to build both parts.
84+
# runtime dependencies
85+
brew install sdl2 ffmpeg
4886

49-
[sdl]: https://www.libsdl.org/
50-
[ffmpeg]: https://www.ffmpeg.org/
51-
[meson]: http://mesonbuild.com/
52-
[ninja]: https://ninja-build.org/
87+
# build dependencies
88+
brew install gcc pkg-config meson zip
5389

90+
Java (>= 7) is not available in Homebrew, so if you plan to build the server,
91+
install it manually and make it available from the `PATH`:
5492

55-
### Build requirements
93+
export PATH="$JAVA_HOME/bin:$PATH"
5694

57-
Install the [Android SDK], the JDK 8 (`openjdk-8-jdk`), and the packages
58-
described below.
5995

60-
[Android SDK]: https://developer.android.com/studio/index.html
96+
### Common steps
6197

98+
Install the [Android SDK] (_Android Studio_), and set `ANDROID_HOME` to
99+
its directory. For example:
62100

63-
#### Linux
101+
[Android SDK]: https://developer.android.com/studio/index.html
64102

65-
sudo apt install make gcc openjdk-8-jdk pkg-config meson zip \
66-
libavcodec-dev libavformat-dev libavutil-dev \
67-
libsdl2-dev libsdl2-net-dev
103+
export ANDROID_HOME=~/android/sdk
68104

105+
Then, build `scrcpy`:
69106

70-
#### Windows
107+
meson x --buildtype release --strip -Db_lto=true
108+
cd x
109+
ninja
71110

72-
Install these packages:
111+
You can test it from here:
73112

74-
pacman -S mingw-w64-x86_64-make
75-
pacman -S mingw-w64-x86_64-gcc
76-
pacman -S mingw-w64-x86_64-pkg-config
77-
pacman -S mingw-w64-x86_64-meson
78-
pacman -S zip
113+
ninja run
79114

80-
Java 8 is not available in MSYS2, so install it manually and make it available
81-
from the `PATH`:
115+
Or you can install it on the system:
82116

83-
export PATH="$JAVA_HOME/bin:$PATH"
117+
sudo ninja install # without sudo on Windows
84118

119+
This installs two files:
85120

86-
### Build
121+
- `/usr/local/bin/scrcpy`
122+
- `/usr/local/share/scrcpy/scrcpy-server.jar`
87123

88-
Make sure your `ANDROID_HOME` variable is set to your Android SDK directory:
124+
Just remove them to "uninstall" the application.
89125

90-
export ANDROID_HOME=~/android/sdk
91126

92-
From the project root directory, execute:
127+
#### Prebuilt server
93128

94-
make build
129+
Since the server binary, that will be pushed to the Android device, does not
130+
depend on your system and architecture, you may want to use the prebuilt binary
131+
instead: [`scrcpy-server.jar`](TODO).
95132

96-
To run the build:
133+
In that case, the build does not require Java or the Android SDK.
97134

98-
make run
135+
Download the prebuilt server somewhere, and specify its path during the Meson
136+
configuration:
99137

100-
It is also pass arguments to `scrcpy` via `make`:
138+
meson x --buildtype release --strip -Db_lto=true \
139+
-Dprebuilt_server=/path/to/scrcpy-server.jar
140+
cd x
141+
ninja
142+
sudo ninja install
101143

102-
make run ARGS="-p 1234"
103144

104-
The purpose of this command is to execute `scrcpy` during the development.
145+
## Run
105146

147+
_At runtime, `adb` must be accessible from your `PATH`._
106148

107-
### Test
149+
If everything is ok, just plug an Android device, and execute:
108150

109-
To execute unit tests:
151+
scrcpy
110152

111-
make test
153+
It accepts command-line arguments, listed by:
112154

113-
The server-side tests require JUnit 4:
155+
scrcpy --help
114156

115-
sudo apt install junit4
157+
For example, to increase video bitrate to 8Mbps (default is 4Mbps):
116158

159+
scrcpy -b 8M
117160

118-
### Generate a release
161+
To limit the video dimensions (e.g. if the device is 2540×1440, but the host
162+
screen is smaller, or cannot decode such a high definition):
119163

120-
From the project root directory, execute:
164+
scrcpy -m 1024
121165

122-
make release
166+
If several devices are listed in `adb devices`, you must specify the _serial_:
123167

124-
This will generate the application in `dist/scrcpy/`.
168+
scrcpy -s 0123456789abcdef
125169

126170

127-
## Run
171+
## Shortcuts
128172

129-
Plug a device, and from `dist/scrcpy/`, execute:
173+
| Action | Shortcut |
174+
| ------------------------------------- | -------------:|
175+
| switch fullscreen mode | `Ctrl`+`f` |
176+
| resize window to 1:1 (pixel-perfect) | `Ctrl`+`g` |
177+
| resize window to remove black borders | `Ctrl`+`x` |
178+
| click on `HOME` | `Ctrl`+`h` |
179+
| click on `BACK` | `Ctrl`+`b` |
180+
| click on `APP_SWITCH` | `Ctrl`+`m` |
181+
| click on `VOLUME_UP` | `Ctrl`+`+` |
182+
| click on `VOLUME_DOWN` | `Ctrl`+`-` |
183+
| click on `POWER` | `Ctrl`+`p` |
184+
| turn screen on | _Right-click_ |
185+
| enable/disable FPS counter (on stdout) | `Ctrl`+`i` |
130186

131-
./scrcpy
132187

133-
If several devices are listed in `adb devices`, you must specify the _serial_:
188+
## Licence
134189

135-
./scrcpy 0123456789abcdef
190+
Copyright (C) 2018 Genymobile
136191

137-
To change the default port (useful to launch several `scrcpy` simultaneously):
192+
Licensed under the Apache License, Version 2.0 (the "License");
193+
you may not use this file except in compliance with the License.
194+
You may obtain a copy of the License at
138195

139-
./scrcpy -p 1234
196+
http://www.apache.org/licenses/LICENSE-2.0
140197

141-
Other options are available, check `scrcpy --help`.
198+
Unless required by applicable law or agreed to in writing, software
199+
distributed under the License is distributed on an "AS IS" BASIS,
200+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201+
See the License for the specific language governing permissions and
202+
limitations under the License.

‎assets/screenshot-debian-600.jpg

43.9 KB
Loading

0 commit comments

Comments
 (0)