Pivot: companion APK camera backend for phones scrcpy cannot use

[opariffazman]

Why this repo exists, and what the first milestone is.

Background

android-cam-tui streams a phone camera into a v4l2loopback sink by driving scrcpy --video-source=camera. That path has a hard floor and a hard wall:

• Floor: upstream scrcpy gates camera capture at Android 12 / API 31 (Add option to mirror camera Genymobile/scrcpy#4213). On Android ≤11 the camera service only serves clients it considers foreground, and the shell uid cannot reliably be one.
• Wall: a patched server that fakes foreground status with an invisible overlay window was tried and does not help on vendor builds that revoke the CAMERA permission from com.android.shell outright.

Measured on OPPO CPH1931 (ColorOS, Android 10, unrooted), with the patched server from officialdad/scrcpy@camera-a10 loaded via SCRCPY_SERVER_PATH:

SecurityException: validateClientPermissionsLocked:1076: Caller "com.android.shell"
(PID 2000, UID 19157) cannot open camera "0" without camera permission

The overlay window itself was created fine — the refusal happens earlier, on permissions. pm grant com.android.shell android.permission.CAMERA is refused too (shell lacks GRANT_RUNTIME_PERMISSIONS on this ROM), and there is no root. Full writeup: officialdad/android-cam-tui#4.

Conclusion: everything that runs as the shell uid is a dead end on this class of device. Only code running as an installed app, holding its own user-granted CAMERA permission, can open the camera.

The pivot

A small companion APK that owns the camera and streams frames to the Linux host, with android-cam-tui gaining a second backend behind the same interface it already uses for StreamRunner.

Sketch, deliberately minimal for v1:

• Capture: Camera2 → MediaCodec H.264, same shape as scrcpy's own encoder.
• Transport: raw Annex-B over a TCP socket on localhost, reached from the host with adb forward tcp:<port> tcp:<port>. USB only, no Wi-Fi, no pairing, no discovery — adb is already a hard dependency of the TUI.
• Host side: existing pipeline, unchanged in spirit — decode and write into the v4l2loopback sink.
• Control: none in v1. Launch with adb shell am start, hardcode back camera at 1280x720@30. Camera/size/fps selection comes later, once the stream works at all.

Open questions to settle before writing much code

1. Background camera access. Android 9+ blocks camera from the background. A foreground service with foregroundServiceType="camera" is the documented route (API 29+), but it still needs the app foregrounded once to start. Does that survive the screen going off?
2. Keyguard interaction. android-cam-tui deliberately never wakes or unlocks the phone: waking a locked device starts face unlock, which opens a camera of its own and pushes the device past the system open-camera limit, so our own open gets rejected. Whatever launch sequence this app needs must not reintroduce that.
3. minSdk. API 21 is cheap to target and covers everything the scrcpy path cannot. Confirm nothing in the encoder path forces higher.
4. Latency budget. scrcpy's camera path is the baseline to beat, or at least match; worth measuring before committing to a socket format.

First milestone

One APK, one hardcoded resolution, one socket, frames landing in /dev/video0 on the OPPO CPH1931 — the exact device that no scrcpy-based path can serve. Everything else is deferred until that works end to end.

[opariffazman]

Answered on hardware rather than on paper — OPPO CPH1931, ColorOS, Android 10, unrooted, screen off and keyguard up throughout. Implementation is in ccae2f9.

1. Background camera access

A foreground service is sufficient on API 29, and no Activity is needed at all. The service is started straight from the host:

adb shell am start-foreground-service -n com.officialdad.androidcam/.CamService

That puts the process at IMPORTANCE_FOREGROUND_SERVICE, which is what the Android 9+ background-camera gate actually checks. It survives the screen going off because the screen was never on:

mScreenOn=false
screenState=SCREEN_STATE_OFF
mDreamingLockscreen=true

3.2 MB of valid H.264 in 4 s in that state — ffprobe reports h264 / 1280x720 / yuvj420p, and a decoded frame is a real picture of the room.

2. Keyguard interaction

The question dissolves rather than gets answered. With no Activity there is no launch sequence to get wrong: am start-foreground-service does not touch the display, so the rule android-cam-tui already follows — never wake, never unlock — is structural here instead of a convention someone has to remember. Face unlock is never armed, so it never takes a camera slot.

3. minSdk

21 confirmed. Nothing in the encoder path forces higher — Camera2 and MediaCodec.createInputSurface are both API 21 and 18. The constraint that mattered was targetSdk, not minSdk: 32, because ≥33 adds the POST_NOTIFICATIONS runtime prompt for the mandatory foreground-service notification, and ≥34 enforces foregroundServiceType. Both are avoidable by not opting in.

foregroundServiceType="camera" is declared anyway; older platforms ignore the unknown attribute.

4. Latency budget

Not measured yet. The socket format survived the milestone unchanged, so nothing is committed that a measurement would invalidate — raw Annex-B has no framing to redesign. Deferring until there is a scrcpy path to compare against on a device that can run one.

Two deviations from the plan above

Transport is localabstract, not TCP. Same adb forward, one word different:

adb forward tcp:27183 localabstract:android-cam

reaching a LocalServerSocket. Costs nothing, drops the INTERNET permission and the port collision, and is the shape scrcpy already uses.

pm grant works for the app. The refusal in the writeup was specific to com.android.shell; this ROM grants CAMERA to a normally-installed app without complaint. adb install -g was enough, no manual trip through Settings:

android.permission.CAMERA: granted=true

That is the whole thesis of the pivot confirmed on the device that motivated it.

Host-side finding worth carrying into the TUI backend

Annex-B carries no timestamps, so ffmpeg probes a bogus tbr 1200k and then drops ~98% of the frames converting down to the output rate — 2 frames in 4 s. Setting the rate on the input and refusing to re-time fixes it:

ffmpeg ... -r 30 -f h264 -i tcp://127.0.0.1:27183 -fps_mode passthrough ...

109 frames in 4 s, no drops. Whatever consumes this stream needs the same two flags.

Build

No Gradle. One class, no resources, no dependencies, so javac + d8 + aapt2 + apksigner are driven directly from build.sh — the repo has no wrapper, no AGP and no lockfile to keep current.

Milestone status

One APK, one hardcoded resolution, one socket, frames in /dev/video0 on the CPH1931 — done. ./run.sh --check streams for three seconds, reads a frame back out of the sink and fails loudly if nothing arrived.

Still deferred, as planned: camera/size/fps selection, any control channel, and the android-cam-tui backend that consumes this.