In practice5 min read

Regions and overviews

Request one overview of the whole screen plus named regions, each at its own size and format.

The common request is not “give me the screen”. It is “tell me roughly what is happening, and show me these two areas properly”. Paying for a full-resolution image to inspect a corner is the thing worth avoiding.

bash

$ eensh session capture "$SID" --json --base64 \
  --overview-width 480 --overview-format jpeg --overview-quality 60 \
  --region 'hud=0,0,1920,180'      --region-format png \
  --region 'map=1600,880,320,200@newest!180' --region-format jpeg --region-quality 80

That returns one cheap overview of the whole screen, a lossless strip where text matters, and a JPEG of a minimap — three views of the same moment, for less than a single full-resolution frame in most cases.

Three views of one moment, rendered from a single capture. The extra views cost no second capture of the display — only the encoding of each, which is the part the per-view format and width control.

What a region may specify

A region is named, and the name is what identifies it in the response. Beyond that it has three optional aspects:

its own image settings: Width, format, and quality, settable per region. A region that does not name its own inherits the --region-* defaults.
a scope@all | @newest | @older: Which frames of a temporal stack the region applies to. Useful when a HUD matters on every frame but a detail panel only matters on the newest one.
a fitting priority@!N: How protected the region is when a payload budget forces the fitter to degrade something. Higher survives longer.

Both suffixes are introduced by @ and comma-separated when combined:

region syntax

name=0,0,320,200              plain
name=0,0,320,200@newest       on the newest frame only
name=0,0,320,200@!180         high fitting priority
name=0,0,320,200@all,!140     both

What each view reports about itself

Each view reports three things about itself, and the third is the one that keeps the response honest:

one view

{
  "name": "hud",
  "kind": "region",
  "source_rect": { "x": 0, "y": 0, "width": 1920, "height": 180 },
  "transform": { "origin": "top-left", "offset_x": 0, "offset_y": 0,
                 "scale_x": 1.0, "scale_y": 1.0 },
  "image": { "width": 1920, "height": 180, "format": "png", "data": "..." },
  "applied": { "format": "png", "width": null,
               "base64": true, "metadata_only": false }
}

source_rect: Where this view came from, in source coordinates. A crop of a window at source (100, 200) reports (100, 200), so a caller never reconstructs the origin.
transform: How to map this view’s own pixels back to the screen — present even when it is the identity, so the contract is unconditional.
applied: The settings actually used, which is not always what was requested once a payload budget has fitted the response. Reported separately so a budget can never quietly change what you received.

Disabling the overview

--no-overview sends only regions. The whole-frame view is genuinely absent rather than present-but-empty, because an agent paying for an overview it did not ask for is the exact cost this exists to avoid.

bash

$ eensh session capture "$SID" --json --base64 --no-overview \
  --region 'status=0,1040,1920,40' --region-format png

Metadata without returning pixels

--metadata-only describes every view — name, source rectangle, transform, and the settings that would have been applied — and embeds no image anywhere. It is the cheapest presentation there is, and useful for deciding which view is worth paying for before asking for it.

A metadata-only view reports "metadata_only": true with a null image. That flag matters: a null image is otherwise indistinguishable from a view that failed to encode.

Next: what happens when even that is too much — bounded payloads.