Skip to content

Display and control your Android device

Document virtual display and "start app" features

Romain Vimont381fe95867fb
diff --git a/README.md b/README.md
index 44f3d740..6e4e513a 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,7 @@ It focuses on:
Its features include:
- [audio forwarding](doc/audio.md) (Android 11+)
- [recording](doc/recording.md)
+ - [virtual display](doc/virtual_display.md)
- mirroring with [Android device screen off](doc/device.md#turn-screen-off)
- [copy-paste](doc/control.md#copy-paste) in both directions
- [configurable quality](doc/video.md)
@@ -91,6 +92,12 @@ Here are just some common examples.
scrcpy --video-codec=h265 -m1920 --max-fps=60 --no-audio -K # short version
```
+ - Start VLC in a new virtual display (separate from the device display):
+
+ ```bash
+ scrcpy --new-display=1920x1080 --start-app=org.videolan.vlc
+ ```
+
- Record the device camera in H.265 at 1920x1080 (and microphone) to an MP4
file:
@@ -134,6 +141,7 @@ documented in the following pages:
- [Device](doc/device.md)
- [Window](doc/window.md)
- [Recording](doc/recording.md)
+ - [Virtual display](doc/virtual_displays.md)
- [Tunnels](doc/tunnels.md)
- [OTG](doc/otg.md)
- [Camera](doc/camera.md)
diff --git a/doc/device.md b/doc/device.md
index 988ad417..ee86c359 100644
--- a/doc/device.md
+++ b/doc/device.md
@@ -78,3 +78,48 @@ By default, on start, the device is powered on. To prevent this behavior:
```bash
scrcpy --no-power-on
```
+
+
+## Start Android app
+
+To list the Android apps installed on the device:
+
+```bash
+scrcpy --list-apps
+```
+
+An app, selected by its package name, can be launched on start:
+
+```
+scrcpy --start-app=org.mozilla.firefox
+```
+
+This feature can be used to run an app in a [virtual
+display](virtual_display.md):
+
+```
+scrcpy --new-display=1920x1080 --start-app=org.videolan.vlc
+```
+
+The app can be optionally forced-stop before being started, by adding a `+`
+prefix:
+
+```
+scrcpy --start-app=+org.mozilla.firefox
+```
+
+For convenience, it is also possible to select an app by its name, by adding a
+`?` prefix:
+
+```
+scrcpy --start-app=?firefox
+```
+
+But retrieving app names may take some time (sometimes several seconds), so
+passing the package name is recommended.
+
+The `+` and `?` prefixes can be combined (in that order):
+
+```
+scrcpy --start-app=+?firefox
+```
diff --git a/doc/virtual_display.md b/doc/virtual_display.md
new file mode 100644
index 00000000..4ed5961f
--- /dev/null
+++ b/doc/virtual_display.md
@@ -0,0 +1,26 @@
+# Virtual display
+
+## New display
+
+To mirror a new virtual display instead of the device screen:
+
+```bash
+scrcpy --new-display=1920x1080
+scrcpy --new-display=1920x1080/420 # force 420 dpi
+scrcpy --new-display # use the main display size and density
+scrcpy --new-display -m1920 # ... scaled to fit a max size of 1920
+scrcpy --new-display=/240 # use the main display size and 240 dpi
+```
+
+## Start app
+
+On some devices, a launcher is available in the virtual display.
+
+When no launcher is available, the virtual display is empty. In that case, you
+must [start an Android app](device.md#start-android-app).
+
+For example:
+
+```bash
+scrcpy --new-display=1920x1080 --start-app=org.videolan.vlc
+```