Add camera documentation

PR #4213 <https://github.com/Genymobile/scrcpy/pull/4213>

README.md

@@ -25,12 +25,13 @@ It focuses on:
 [lowlatency]: https://github.com/Genymobile/scrcpy/pull/646
 
 Its features include:
- - [audio forwarding](doc/audio.md) (Android >= 11)
+ - [audio forwarding](doc/audio.md) (Android 11+)
  - [recording](doc/recording.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)
- - Android device screen [as a webcam (V4L2)](doc/v4l2.md) (Linux-only)
+ - [camera mirroring](doc/camera.md) (Android 12+)
+ - [mirroring as a webcam (V4L2)](doc/v4l2.md) (Linux-only)
  - [physical keyboard/mouse simulation (HID)](doc/hid-otg.md)
  - [OTG mode](doc/hid-otg.md#otg)
  - and more…
@@ -77,6 +78,7 @@ documented in the following pages:
  - [Recording](doc/recording.md)
  - [Tunnels](doc/tunnels.md)
  - [HID/OTG](doc/hid-otg.md)
+ - [Camera](doc/camera.md)
  - [Video4Linux](doc/v4l2.md)
  - [Shortcuts](doc/shortcuts.md)
 

app/data/bash-completion/scrcpy

@@ -14,6 +14,7 @@ _scrcpy() {
         --camera-id=
         --camera-facing=
         --camera-fps=
+        --camera-high-speed
         --camera-size=
         --crop=
         -d --select-usb

app/data/zsh-completion/_scrcpy

@@ -18,6 +18,7 @@ arguments=(
     '--audio-output-buffer=[Configure the size of the SDL audio output buffer (in milliseconds)]'
     {-b,--video-bit-rate=}'[Encode the video at the given bit-rate]'
     '--camera-ar=[Select the camera size by its aspect ratio]'
+    '--camera-high-speed=[Enable high-speed camera capture mode]'
     '--camera-id=[Specify the camera id to mirror]'
     '--camera-facing=[Select the device camera by its facing direction]:facing:(front back external)'
     '--camera-fps=[Specify the camera capture frame rate]'

app/scrcpy.1

@@ -81,6 +81,12 @@ Select the camera size by its aspect ratio (+/- 10%).
 
 Possible values are "sensor" (use the camera sensor aspect ratio), "<num>:<den>" (e.g. "4:3") and "<value>" (e.g. "1.6").
 
+.TP
+.B \-\-camera\-high\-speed
+Enable high-speed camera capture mode.
+
+This mode is restricted to specific resolutions and frame rates, listed by --list-camera-sizes.
+
 .TP
 .BI "\-\-camera\-id " id
 Specify the device camera id to mirror.

app/src/cli.c

@@ -2290,19 +2290,13 @@ parse_args_with_getopt(struct scrcpy_cli_args *args, int argc, char *argv[],
             return false;
         }
 
-        if (opts->lock_video_orientation !=
-                SC_LOCK_VIDEO_ORIENTATION_UNLOCKED) {
-            LOGE("--lock-video-orientation is not supported for camera");
-            return false;
-        }
-
         if (opts->camera_id && opts->camera_facing != SC_CAMERA_FACING_ANY) {
             LOGE("Could not specify both --camera-id and --camera-facing");
             return false;
         }
 
         if (opts->camera_size) {
-            if (opts->camera_ar) {
+            if (opts->max_size) {
                 LOGE("Could not specify both --camera-size and -m/--max-size");
                 return false;
             }

doc/camera.md

@@ -0,0 +1,150 @@
+# Camera
+
+Camera mirroring is supported for devices with Android 12 or higher.
+
+To capture the camera instead of the device screen:
+
+```
+scrcpy --video-source=camera
+```
+
+By default, it automatically switches [audio source](audio.md#source) to
+microphone (as if `--audio-source=mic` were also passed).
+
+```bash
+scrcpy --video-source=display  # default is --audio-source=output
+scrcpy --video-source=camera   # default is --audio-source=mic
+scrcpy --video-source=display --audio-source=mic    # force display AND microphone
+scrcpy --video-source=camera --audio-source=output  # force camera AND device audio output
+```
+
+
+## List
+
+To list the cameras available (with their declared valid sizes and frame rates):
+
+```
+scrcpy --list-cameras
+scrcpy --list-camera-sizes
+```
+
+_Note that the sizes and frame rates are declarative. They are not accurate on
+all devices: some of them are declared but not supported, while some others are
+not declared but supported._
+
+
+## Selection
+
+It is possible to pass an explicit camera id (as listed by `--list-cameras`):
+
+```
+scrcpy --video-source=camera --camera-id=0
+```
+
+Alternatively, the camera may be selected automatically:
+
+```bash
+scrcpy --video-source=camera                           # use the first camera
+scrcpy --video-source=camera --camera-facing=front     # use the first front camera
+scrcpy --video-source=camera --camera-facing=back      # use the first back camera
+scrcpy --video-source=camera --camera-facing=external  # use the first external camera
+```
+
+If `--camera-id` is specified, then `--camera-facing` is forbidden (the id
+already determines the camera):
+
+```bash
+scrcpy --video-source=camera --camera-id=0 --camera-facing=front  # error
+```
+
+
+### Size selection
+
+It is possible to pass an explicit camera size:
+
+```
+scrcpy --video-source=camera --camera-size=1920x1080
+```
+
+The given size may be listed among the declared valid sizes
+(`--list-camera-sizes`), but may also be anything else (some devices support
+arbitrary sizes):
+
+```
+scrcpy --video-source=camera --camera-size=1840x444
+```
+
+Alternatively, a declared valid size (among the ones listed by
+`list-camera-sizes`) may be selected automatically.
+
+Two constraints are supported:
+ - `-m`/`--max-size` (already used for display mirroring), for example `-m1920`;
+ - `--camera-ar` to specify an aspect ratio (`<num>:<den>`, `<value>` or
+   `sensor`).
+
+Some examples:
+
+```bash
+scrcpy --video-source=camera                          # use the greatest width and the greatest associated height
+scrcpy --video-source=camera -m1920                   # use the greatest width not above 1920 and the greatest associated height
+scrcpy --video-source=camera --camera-ar=4:3          # use the greatest size with an aspect ratio of 4:3 (+/- 10%)
+scrcpy --video-source=camera --camera-ar=1.6          # use the greatest size with an aspect ratio of 1.6 (+/- 10%)
+scrcpy --video-source=camera --camera-ar=sensor       # use the greatest size with the aspect ratio of the camera sensor (+/- 10%)
+scrcpy --video-source=camera -m1920 --camera-ar=16:9  # use the greatest width not above 1920 and the closest to 16:9 aspect ratio
+```
+
+If `--camera-size` is specified, then `-m`/`--max-size` and `--camera-ar` are
+forbidden (the size is determined by the value given explicitly):
+
+```bash
+scrcpy --video-source=camera --camera-size=1920x1080 -m3000  # error
+```
+
+
+## Frame rate
+
+By default, camera is captured at Android's default frame rate (30 fps).
+
+To configure a different frame rate:
+
+```
+scrcpy --video-source=camera --camera-fps=60
+```
+
+
+## High speed capture
+
+The Android camera API also supports a [high speed capture mode][high speed].
+
+This mode is restricted to specific resolutions and frame rates, listed by
+`--list-camera-sizes`.
+
+```
+scrcpy --video-source=camera --camera-size=1920x1080 --camera-fps=240
+```
+
+[high speed]: https://developer.android.com/reference/android/hardware/camera2/CameraConstrainedHighSpeedCaptureSession
+
+
+## Brace expansion tip
+
+All camera options start with `--camera-`, so if your shell supports it, you can
+benefit from [brace expansion] (for example, it is supported _bash_ and _zsh_):
+
+```bash
+scrcpy --video-source=camera --camera-{facing=back,ar=16:9,high-speed,fps=120}
+```
+
+This will be expanded as:
+
+```bash
+scrcpy --video-source=camera --camera-facing=back --camera-ar=16:9 --camera-high-speed --camera-fps=120
+```
+
+[brace expansion]: https://www.gnu.org/software/bash/manual/html_node/Brace-Expansion.html
+
+
+## Webcam
+
+Combined with the [V4L2](v4l2.md) feature on Linux, the Android device camera
+may be used as a webcam on the computer.

doc/video.md

@@ -1,5 +1,14 @@
 # Video
 
+## Source
+
+By default, scrcpy mirrors the device screen.
+
+It is possible to capture the device camera instead.
+
+See the dedicated [camera](camera.md) page.
+
+
 ## Size
 
 By default, scrcpy attempts to mirror at the Android device resolution.

server/src/main/java/com/genymobile/scrcpy/CameraCapture.java

@@ -227,7 +227,7 @@ public class CameraCapture extends SurfaceCapture {
         this.maxSize = maxSize;
         try {
             size = selectSize(cameraId, null, maxSize, aspectRatio, highSpeed);
-            return true;
+            return size != null;
         } catch (CameraAccessException e) {
             Ln.w("Could not select camera size", e);
             return false;

server/src/main/java/com/genymobile/scrcpy/CameraFacing.java

@@ -1,10 +1,12 @@
 package com.genymobile.scrcpy;
 
+import android.annotation.SuppressLint;
 import android.hardware.camera2.CameraCharacteristics;
 
 public enum CameraFacing {
     FRONT("front", CameraCharacteristics.LENS_FACING_FRONT),
     BACK("back", CameraCharacteristics.LENS_FACING_BACK),
+    @SuppressLint("InlinedApi") // introduced in API 23
     EXTERNAL("external", CameraCharacteristics.LENS_FACING_EXTERNAL);
 
     private final String name;

server/src/main/java/com/genymobile/scrcpy/LogUtils.java

@@ -11,9 +11,7 @@ import android.hardware.camera2.params.StreamConfigurationMap;
 import android.media.MediaCodec;
 import android.util.Range;
 
-import java.util.Arrays;
 import java.util.List;
-import java.util.Set;
 import java.util.SortedSet;
 import java.util.TreeSet;
 
@@ -119,7 +117,7 @@ public final class LogUtils {
 
                         android.util.Size[] highSpeedSizes = configs.getHighSpeedVideoSizes();
                         if (highSpeedSizes.length > 0) {
-                            builder.append("\n      High speed capture:");
+                            builder.append("\n      High speed capture (--camera-high-speed):");
                             for (android.util.Size size : highSpeedSizes) {
                                 Range<Integer>[] highFpsRanges = configs.getHighSpeedVideoFpsRanges();
                                 SortedSet<Integer> uniqueHighFps = getUniqueSet(highFpsRanges);

server/src/main/java/com/genymobile/scrcpy/ScreenCapture.java

@@ -48,8 +48,8 @@ public class ScreenCapture extends SurfaceCapture implements Device.RotationList
     }
 
     @Override
-    public boolean setMaxSize(int size) {
-        device.setMaxSize(size);
+    public boolean setMaxSize(int maxSize) {
+        device.setMaxSize(maxSize);
         return true;
     }
 

server/src/main/java/com/genymobile/scrcpy/Server.java

@@ -104,8 +104,8 @@ public final class Server {
         boolean video = options.getVideo();
         boolean audio = options.getAudio();
         boolean sendDummyByte = options.getSendDummyByte();
+        boolean camera = options.getVideoSource() == VideoSource.CAMERA;
 
-        boolean camera = true;
         Workarounds.apply(audio, camera);
 
         List<AsyncProcessor> asyncProcessors = new ArrayList<>();

server/src/main/java/com/genymobile/scrcpy/SurfaceCapture.java

@@ -56,9 +56,9 @@ public abstract class SurfaceCapture {
     /**
      * Set the maximum capture size (set by the encoder if it does not support the current size).
      *
-     * @param size Maximum size
+     * @param maxSize Maximum size
      */
-    public abstract boolean setMaxSize(int size);
+    public abstract boolean setMaxSize(int maxSize);
 
     /**
      * Indicate if the capture has been closed internally.

server/src/main/java/com/genymobile/scrcpy/VideoCodec.java

@@ -6,7 +6,7 @@ import android.media.MediaFormat;
 public enum VideoCodec implements Codec {
     H264(0x68_32_36_34, "h264", MediaFormat.MIMETYPE_VIDEO_AVC),
     H265(0x68_32_36_35, "h265", MediaFormat.MIMETYPE_VIDEO_HEVC),
-    @SuppressLint("InlinedApi") // introduced in API 21
+    @SuppressLint("InlinedApi") // introduced in API 29
     AV1(0x00_61_76_31, "av1", MediaFormat.MIMETYPE_VIDEO_AV1);
 
     private final int id; // 4-byte ASCII representation of the name