Screenshots & Recording

Capturing the device screen and saving it to this server's host. take_screenshot runs adb exec-out screencap -p and writes a PNG to <ADB_AUTOMATION_LOCAL_ROOT>/screenshots/; record_screen runs adb shell screenrecord for a bounded duration and saves the MP4. Both return the saved path and metadata, never the file bytes inline, and fail with POLICY_DENIED if ADB_AUTOMATION_LOCAL_ROOT is unset.

record_screen

Record the device screen to an MP4, save it to the host, return the path.

Runs adb shell screenrecord --time-limit <duration_s> against a device-side temp file, adb pulls the result into <ADB_AUTOMATION_LOCAL_ROOT>/recordings/, and always removes the device-side temp file afterward. screenrecord stops itself at the duration limit, so this call blocks for roughly duration_s seconds. Only the primary display is recorded.

Parameters:

Name	Type	Description	Default
serial	str	The target device's adb serial (see list_connected_devices).	required
duration_s	int	How long to record, in seconds. Must be between 1 and 180 (screenrecord's own maximum); there is no unlimited option. Defaults to 10.	10
size	str | None	Video frame size as "x", e.g. "1280x720". Omit to use the display's native resolution. Must match the AVC encoder's constraints or screenrecord fails.	None
bit_rate_mbps	float | None	Target video bit rate in megabits per second (e.g. 4 or 8). Must be > 0 and <= 100. Omit for screenrecord's default (20 Mbps).	None
bugreport	bool	Overlay a timestamp and device-info frame, as screenrecord's --bugreport does — useful when the recording documents a bug.	False
verbose	bool	Pass screenrecord's --verbose, surfacing its progress lines in the result's output field.	False
filename	str | None	Bare filename for the saved file (no path separators); .mp4 is appended if missing. Omit for an auto name like recording-<serial>-<UTC timestamp>.mp4.	None

Returns:

Type	Description
ScreenRecordingResult	The serial, the absolute local_path the .mp4 was saved to, the duration_s / size / bit_rate_mbps / bugreport / verbose used, size_bytes (the saved file's size, or None if it couldn't be stat'd), and output (screenrecord's stdout — progress lines when verbose, otherwise empty).

Error handling

duration_s out of range, a malformed size, or a bit_rate_mbps outside (0, 100] is rejected before any device round-trip (INVALID_ARGUMENT). No ADB_AUTOMATION_LOCAL_ROOT configured, or a filename that resolves outside it / contains a path separator, raises POLICY_DENIED / INVALID_ARGUMENT. An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE; a recording that runs past its expected duration without returning raises TIMEOUT. A permission rejection raises PERMISSION_DENIED; screenrecord failing to initialize the encoder or write its file, or any other failure, raises BACKEND_ERROR. The device-side temp file is removed on every path.

Example

Called with serial="emulator-5554", duration_s=5, filename="run1". A typical response:

{
  "status": "success",
  "message": "Recorded 5s of emulator-5554 to /srv/adb/recordings/run1.mp4.",
  "data": {
    "serial": "emulator-5554",
    "local_path": "/srv/adb/recordings/run1.mp4",
    "duration_s": 5,
    "size": null,
    "bit_rate_mbps": null,
    "bugreport": false,
    "verbose": false,
    "size_bytes": 481234,
    "success": true,
    "output": ""
  },
  "error": null
}

take_screenshot

Capture the device's screen as a PNG, save it to the host, return the path.

Runs adb exec-out screencap -p, writes the PNG to <ADB_AUTOMATION_LOCAL_ROOT>/screenshots/, and returns the absolute path it was saved to (plus width/height/size). The caller reads the image from that path — no image bytes are returned inline.

Parameters:

Name	Type	Description	Default
serial	str	The target device's adb serial (see list_connected_devices).	required
display_id	int | None	Capture one specific display (-d, see list_displays) on a multi-display device. Omit to capture the default display.	None
filename	str | None	Bare filename for the saved file (no path separators); .png is appended if missing. Omit for an auto name like screenshot-<serial>-<UTC timestamp>.png.	None

Returns:

Type	Description
TakeScreenshotResult	The serial, display_id, the absolute local_path the PNG was saved to, best-effort width/height read from the PNG header, and size_bytes.

Error handling

No ADB_AUTOMATION_LOCAL_ROOT configured (or a filename that resolves outside it) raises POLICY_DENIED. A filename containing a path separator raises INVALID_ARGUMENT. An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. A permission rejection raises PERMISSION_DENIED. If screencap runs but returns no PNG data (e.g. an invalid display_id on some builds), or any other non-zero exit, this raises BACKEND_ERROR.

Example

Called with serial="emulator-5554". A typical response:

{
  "status": "success",
  "message": "Saved 1080x2400 screenshot from emulator-5554 to /srv/adb/screenshots/screenshot-emulator-5554-20260830-101500.png.",
  "data": {
    "serial": "emulator-5554",
    "display_id": null,
    "local_path": "/srv/adb/screenshots/screenshot-emulator-5554-20260830-101500.png",
    "width": 1080,
    "height": 2400,
    "size_bytes": 843221,
    "success": true
  },
  "error": null
}