JPEG Screenshots

Configure periodic Android JPEG session capture and on-demand VisualTree screenshots.

Android exposes screenshots through two paths:

periodic session JPEG capture while a paired live session is open
on-demand ui.get_screenshot from the VisualTree tools

Important: Screen capture will result in an FPS drop while the SDK captures, encodes, and transports frames. Use conservative interval, quality, and max-width settings, and disable session JPEG capture for trend-focused runs unless visual evidence is required.

Session Capture

The developer preset enables JPEG capture every 2000 ms, quality 60, max width 480.

For core setup:

import ai.ansight.runtime.AnsightSessionJpegCaptureMode

val options = AnsightOptions.createBuilder()
    .withSessionJpegCapture(
        intervalMilliseconds = 2000,
        quality = 60,
        maxWidth = 480,
        captureGpuBackedSurfaces = true,
        mode = AnsightSessionJpegCaptureMode.ScreenshotAndVisualTree,
        captureKeyboardPresence = true,
    )
    .build()

Disable periodic capture:

val options = AnsightOptions.createBuilder()
    .withoutSessionJpegCapture()
    .build()

Visual-Tree and Keyboard Metadata

Mode	Behavior
`ScreenshotOnly`	Sends periodic JPEG frames without an SDK visual-tree snapshot. This is the default.
`ScreenshotAndVisualTree`	Captures the registered visual-tree sources with each app-owned screenshot and correlates them through the screenshot capture timestamp.
`ScreenshotWithVisualTreeOnTouch`	Keeps periodic screenshots, but captures visual trees on touch down and touch up instead of for every frame. Move and cancel events do not trigger a tree.

Tree capture requires a registered session visual-tree provider. Touch-triggered mode also requires touch capture to remain enabled. Visual-tree payloads follow the compact v2 contract.

captureKeyboardPresence defaults to false. When enabled, replay-frame metadata records only whether the on-screen keyboard was present; it does not collect keyboard contents or dimensions. Keyboard-presence metadata also remains useful when the host owns simulator/emulator screenshots.

Emulator Capture Ownership

The runtime advertises sessionJpegCaptureControlVersion: 1 in device.profile. The resident host can acknowledge the profile with sessionJpegCapture.mode: "host" and an optional source such as adb.

In host mode, the SDK suspends its periodic in-app JPEG loop for that live session so the host can capture the emulator externally. A missing response or mode: "app" keeps the configured SDK capture behavior. This negotiation is automatic and does not affect manual capture or ui.get_screenshot.

Manual Frame Capture

val result = AnsightRuntime.captureScreenFrame(
    AnsightSessionJpegCaptureOptions(
        quality = 60,
        maxWidth = 480,
        captureGpuBackedSurfaces = true,
    ),
)

A connected live session is required.

captureGpuBackedSurfaces is accepted for cross-platform configuration parity and defaults to true. The capture-mode tradeoff is currently meaningful on iOS, where setting it to false selects a lower-overhead path that may miss GPU-backed surfaces.

On-Demand Screenshot Tool

The all-in-one package registers AndroidVisualTreeTools.create(), including ui.get_screenshot.

Arguments supported by the tool include format, quality, maxWidth, and chunkBytes. Screenshot bytes are transferred over the Ansight binary transfer protocol when a live tool request is active.