capturing-screenshots-and-screenrecord

name	capturing-screenshots-and-screenrecord
description	Use this skill to capture visual artefacts from a device for test failures, golden image generation, QA repro, and demo videos. Covers `adb shell screencap -p` (PNG screenshot), `adb exec-out screencap -p > out.png` (binary-clean stream that avoids CRLF translation on Windows), `adb shell screenrecord` with `--size`, `--bit-rate`, `--time-limit`, `--rotate`, `--bugreport`, `--verbose` flags, the 3-minute hard cap, scoped-storage rules for `/sdcard/` on API 30+, and the JUnit4 TestWatcher capture-on-failure pattern that grabs a screencap plus `logcat -d` on failure. If the user mentions "screenshot device", "screencap PNG", "raw RGBA dump", "screenrecord 3 minute limit", "scrcpy / Vysor streaming", "exec-out vs shell", or "bugreport overlay timestamp", use this skill.
license	Apache-2.0. See LICENSE for complete terms.
metadata	{"author":"Jaewoong Eum (skydoves)","keywords":["android-testing","adb","screencap","screenrecord","capture-on-failure","test-artifacts","exec-out","scoped-storage","golden-images"]}

Capturing Screenshots and screenrecord — Visual Artefacts For Tests

This skill covers grabbing PNG screenshots and MP4 screen recordings from a device through adb, plus the JUnit4 TestWatcher pattern for capturing on test failure. It does not cover Android Studio's screenshot tool, Compose captureToImage(), or third-party streaming tools (scrcpy/Vysor).

When to use this skill

• A flaky CI test needs a screenshot at the moment of failure plus a logcat dump.
• The team generates golden screenshots from a reference device for visual regression.
• QA needs to record a 30 s repro of a bug for a bug report attachment.
• The dev's adb shell screencap /sdcard/out.png produces a corrupt file — the missing -p flag wrote raw RGBA, not PNG.
• A Windows CI agent receives screenshots with CRLF corruption — the fix is adb exec-out screencap -p.

When NOT to use this skill

• Compose-level screenshot tests using captureToImage() / Roborazzi / Paparazzi. Those are unit-test mechanisms and live under the Compose set, not ADB.
• Continuous live mirroring of the device (presentations, demos). Use scrcpy or Vysor — screenrecord cannot stream.
• Driving the device first (taps, key events). Use ../../control/injecting-input-and-state/SKILL.md.
• Pulling files generally (not screenshots). Use ../../transfer/extracting-test-artifacts/SKILL.md.

Prerequisites

• adb get-state returns device. See ../../devices/connecting-to-devices/SKILL.md.
• For screenrecord: device API 19+ (Android 4.4) — screenrecord was added in KitKat.
• For screenrecord + Wear OS: not supported. The utility refuses (developer.android.com/tools/adb#screenrecord).
• For /sdcard/ writes on API 30+: scoped-storage rules apply; the shell user retains FUSE/sdcardfs access, but app-private writes route through /sdcard/Android/data/<pkg>/.

screencap — PNG screenshots

"The screencap command is a shell utility for taking a screenshot of a device display." — developer.android.com/tools/adb#screencap

screencap [-h] [-p] [-d <displayId>] [<path-on-device>]

Flag	Meaning
(no flag)	Writes raw RGBA framebuffer to file. Not a PNG.
-p	Encode as PNG. Required when streaming to stdout for the host.
-d <displayId>	Capture a specific logical display (multi-display devices).
-h	Help.

Three idiomatic invocations:

# 1. Save to device, then pull (good when the test continues running).
adb shell screencap -p /sdcard/screen.png
adb pull /sdcard/screen.png ./screen.png

# 2. Stream PNG bytes back to host without an intermediate file.
adb exec-out screencap -p > screen.png

# 3. Multi-display capture: external display + main.
adb shell screencap -p -d 0 /sdcard/main.png
adb shell screencap -p -d 1 /sdcard/external.png

exec-out vs shell — the binary-clean trap

adb shell sets up a PTY by default, which on some hosts (notably Windows) translates \n into \r\n on the way out. For binary streams (PNG, MP4, tar archives) this corrupts the file. adb exec-out is the binary-clean stdout variant.

Recipe — never use adb shell screencap -p > out.png for the streaming variant on Windows. Always:

adb exec-out screencap -p > out.png

For files written on the device first and pulled afterwards, the issue does not apply (adb pull is binary-clean).

screenrecord — MP4 screen recording

"The screenrecord command is a shell utility for recording the display of devices running Android 4.4 (API level 19) and higher. The utility records screen activity to an MPEG-4 file." — developer.android.com/tools/adb#screenrecord

screenrecord [--size WIDTHxHEIGHT] [--bit-rate RATE] [--time-limit TIME]
             [--rotate] [--bugreport] [--verbose] <path-on-device>

Flag	Verbatim meaning (developer.android.com/tools/adb#screenrecord)
--help	"Display command syntax and options".
--size WxH	"Set the video size. The default value is the device's native display resolution (if supported), 1280x720 if not."
--bit-rate R	"Set the video bit rate for the video, in megabits per second. The default value is 20Mbps."
--time-limit T	"Set the maximum recording time, in seconds. The default and maximum value is 180 (3 minutes)."
--rotate	"Rotate the output 90 degrees. This feature is experimental."
--bugreport	Embeds a textual frame info / timestamp overlay used by bug-report attachments.
--verbose	"Display log information on the command-line screen."

Hard limits (verbatim)

• "Audio is not recorded with the video file."
• "Video recording is not available for devices running Wear OS."
• "Some devices might not be able to record at their native display resolution. If you encounter problems with screen recording, try using a lower screen resolution."
• "Rotation of the screen during recording is not supported."
• The default and maximum time limit is 180 s. To capture longer scenarios, chain multiple invocations and concatenate post-hoc, or use scrcpy.

No streaming flag — the limitation

screenrecord writes a single MP4 to the device-side path; it does not stream to stdout. For live mirroring (presentations, demos), use scrcpy or Vysor (out of scope for this skill — both bypass screenrecord entirely).

Output paths

Path	When
/sdcard/run.mp4	Default. User-visible video. Scoped-storage rules apply on API 30+ but shell user has FUSE/sdcardfs access.
/data/local/tmp/run.mp4	Use when the test app must produce output before the SD card is mounted, or to avoid touching the public store. Always pullable by shell.

Stopping early

screenrecord runs until --time-limit elapses or it receives SIGINT. From an interactive shell, Ctrl+C. From a script, send the signal to the on-device process:

adb shell screenrecord --time-limit 180 /sdcard/run.mp4 &
REC=$!
# … run instrumentation; on failure, send SIGINT to the on-device process …
adb shell pkill -INT screenrecord
wait $REC
adb pull /sdcard/run.mp4 ./run.mp4

--bugreport overlay

--bugreport adds a frame-info + timestamp overlay to every frame, useful for QA repros where the bug-report-side timestamp must align with logcat. Pair with adb logcat -v threadtime,year,UTC to correlate frame numbers and log lines (see ../../observability/extracting-logs-with-logcat/SKILL.md).

Capture-on-failure pattern (JUnit4 TestWatcher)

The standard pattern: a TestRule or TestWatcher fires failed() on test failure, runs screencap + logcat -d, and pulls the artefacts to a per-test directory.

class CaptureOnFailureRule(private val outputDir: File) : TestWatcher() {
    override fun failed(e: Throwable, description: Description) {
        val testName = "${description.className}.${description.methodName}"
        val device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
        val target = File(outputDir, testName).apply { mkdirs() }

        // PNG screenshot
        device.executeShellCommand("screencap -p /sdcard/fail.png")
        device.executeShellCommand("logcat -d -v threadtime").let { log ->
            File(target, "logcat.txt").writeText(log)
        }
        // The test process can pull /sdcard/fail.png via Context.getExternalFilesDir
        // or push through TestStorageService — see ../../transfer/extracting-test-artifacts/SKILL.md.
    }
}

Host-side equivalent in a CI script (see ../../automation/scripting-adb-for-ci/SKILL.md for the full version):

set +e
./gradlew connectedDebugAndroidTest
RC=$?
set -e

if [ "$RC" -ne 0 ]; then
  mkdir -p artifacts
  adb shell screencap -p /sdcard/fail.png
  adb pull /sdcard/fail.png artifacts/fail.png
  adb logcat -d -v threadtime > artifacts/logcat.txt
  adb logcat -d -b crash      -v threadtime > artifacts/crash.txt
fi
exit $RC

This captures the device's last frame plus a logcat dump only on failure (saves CI storage on green runs). For richer per-test artefact routing, prefer the AndroidX TestStorageService API — see ../../transfer/extracting-test-artifacts/SKILL.md.

Patterns

Pattern: WRONG — screencap without -p

# WRONG
adb shell screencap /sdcard/out.png
file /sdcard/out.png      # → "data" (not a PNG)
# WRONG because: without -p, screencap writes a raw RGBA framebuffer (header + naked pixel
# bytes), not a PNG. Image viewers refuse to open it. The .png extension is misleading.

# RIGHT
adb shell screencap -p /sdcard/out.png
adb pull /sdcard/out.png ./out.png

Pattern: WRONG — adb shell screencap -p > out.png on Windows

# WRONG (on Windows / certain CI hosts)
adb shell screencap -p > out.png
# WRONG because: `adb shell` allocates a PTY and translates LF to CRLF on stdout. For
# binary streams (PNG bytes) this corrupts the file.

# RIGHT (binary-clean stdout)
adb exec-out screencap -p > out.png

Pattern: long capture exceeds 3-minute cap

# WRONG — assumes a single screenrecord can capture 10 minutes
adb shell screenrecord --time-limit 600 /sdcard/run.mp4
# WRONG because: --time-limit is capped at 180. The utility silently truncates to 180.

# RIGHT — chain
for i in 1 2 3 4; do
  adb shell screenrecord --time-limit 180 /sdcard/run-$i.mp4
done
adb pull /sdcard/run-1.mp4 ./
adb pull /sdcard/run-2.mp4 ./
adb pull /sdcard/run-3.mp4 ./
adb pull /sdcard/run-4.mp4 ./
# Concatenate with ffmpeg if needed:
# ffmpeg -f concat -i list.txt -c copy out.mp4

(Or switch to scrcpy for indefinite-duration captures.)

Pattern: bug-report overlay for QA repros

adb shell screenrecord --bugreport --time-limit 60 \
  --bit-rate 8000000 --size 720x1280 /sdcard/repro.mp4
# Each frame has a frame-info + timestamp overlay aligning with logcat -v threadtime,year,UTC.
adb pull /sdcard/repro.mp4 ./repro.mp4
adb logcat -d -v threadtime,year,UTC > repro-logcat.txt

Mandatory rules

• MUST pass -p to screencap for PNG output. Without it, the file is raw RGBA and unusable in image viewers.
• MUST prefer adb exec-out screencap -p > out.png over adb shell screencap -p > out.png for streaming captures, especially on Windows or any CI host where \n → \r\n translation may apply.
• MUST treat screenrecord --time-limit as bounded by 180 s. Anything longer requires chaining or scrcpy.
• MUST stop screenrecord with adb shell pkill -INT screenrecord (not kill -9 from the host) — SIGKILL leaves the MP4 unfinalised and unplayable.
• MUST NOT assume screenrecord captures audio — it does not (developer.android.com/tools/adb#screenrecord).
• MUST NOT use screenrecord on Wear OS — unsupported.
• PREFERRED: capture-on-failure only (not on every run). Saves CI storage and points at the failing test directly.
• PREFERRED: pair every screenrecord --bugreport with a logcat -v threadtime,year,UTC dump captured at the same time. The overlay is otherwise hard to correlate.

Verification

• file ./out.png reports PNG image data after adb shell screencap -p /sdcard/out.png && adb pull /sdcard/out.png.
• On Windows CI, screenshots stream via adb exec-out screencap -p > out.png (no \r\n corruption).
• CI captures screencap and logcat -d only when the test exit code is non-zero.
• No screenrecord --time-limit <N> with N > 180 exists in any script.
• No kill -9 on a screenrecord process — only pkill -INT screenrecord so the MP4 finalises.
• CI artefact archive contains per-test sub-directories named after Class.method.

References

• developer.android.com/tools/adb#screencap — screencap syntax, -p flag, exec-out streaming.
• developer.android.com/tools/adb#screenrecord — screenrecord syntax, flags, hard limits ("Audio is not recorded", 180 s cap, no Wear OS, no rotation mid-recording).
• developer.android.com/tools/adb#shellcommands — quoting + the exec-out vs shell distinction.
• developer.android.com/training/testing/instrumented-tests/stability — screenshot/repro hygiene in instrumented tests.
• Research note tasks/research/A2-adb-shell-commands.md — full screencap / screenrecord flag tables.
• Research note tasks/research/A3-adb-observability-automation.md — capture-on-failure CI pattern; exec-out rationale.
• Sibling skill: ../../architecture/understanding-adb-architecture/SKILL.md — server / daemon / adb shell vs adb exec-out.
• Sibling skill: ../../devices/connecting-to-devices/SKILL.md — adb get-state, multi-device targeting.
• Sibling skill: ../../devices/connecting-over-wifi/SKILL.md — adb pair for wireless capture.
• Sibling skill: ../../apps/installing-and-managing-apps/SKILL.md — installing APKs to capture against.
• Sibling skill: ../../tests/running-instrumented-tests-via-adb/SKILL.md — am instrument invocation.
• Sibling skill: ../../control/injecting-input-and-state/SKILL.md — driving gestures before capturing.
• Sibling skill: ../../observability/extracting-logs-with-logcat/SKILL.md — companion logcat capture in capture-on-failure.
• Sibling skill: ../../transfer/extracting-test-artifacts/SKILL.md — adb pull and TestStorageService.
• Sibling skill: ../../automation/scripting-adb-for-ci/SKILL.md — full CI capture-on-failure pattern.
• Cross-set: ../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md — the JUnit4 TestWatcher mechanic.
• Cross-set: ../../../instrumentation/scenarios/launching-activities-with-activityscenario/SKILL.md — driving an Activity to the failing state before capture.