Getting started4 min read

Your first capture

Run one capture command, then read back each part of what it returns.

Start with the smallest useful command, then add one thing at a time. Each addition below is a decision you will have to make eventually, so it is worth seeing what it changes.

bash

$ eensh capture --display :1 --json --base64

That captures the whole display and returns one JSON document on stdout, with the image embedded. It is the agent-facing default, and it is the only form where the response is self-contained.

Choosing what to capture

Three target options. Without any of them you get the whole root window, which is worth understanding precisely, because it is not always the same thing as “my screen”.

bash

$ eensh capture --display :1                          # whole root window
eensh capture --display :1 --region 100,200,800,600  # a rectangle
eensh capture --display :1 --window 0x4600007        # a single window

The whole root window is not one monitor

On a multi-head setup the root window is the virtual canvas, which can be much larger than any physical display. A machine with a 3840×1600 monitor and a second output may report a root of 7680×2160 — 2.7× the pixels, all of them transferred and encoded.

A bare capture therefore does more work than you might picture. Check what the server reports before assuming:

bash

$ xdpyinfo | grep dimensions

--region is the only lever that reduces both the transfer and the encode. See the performance model for why --width only affects one of them.

--region and --window are mutually exclusive. A region that does not fit inside the display is an error — never clipped silently — so asking for a rectangle you are not sure about is safe.

Choosing the image

Option	Meaning
--format	`png` or `jpeg`. Defaults to `png`, or is inferred from the output file extension.
--quality	JPEG quality, 1–100. Default `80`.
--compression	PNG effort: `fast`, `default`, or `best`. Read the trap below before using the default on a large screen.
--width / --height / --scale	Proportionate resize. The three are mutually exclusive, because asking for a width and a height that disagree would distort the image, and that is never what was meant.

Choosing where it goes

Image bytes and JSON are never interleaved on one stream. The rule is short:

--json	--base64	Output	stdout carries
no	no	any	image bytes
yes	no	a file	JSON
yes	no	-	image bytes, with JSON on stderr
yes	yes	file or stdout	JSON, including the image

Only the last row suppresses raw bytes, because only there does the JSON already carry them. --base64 without --json is rejected outright: there would be no document to put the payload in.

Asking where the time went

--time prints a per-stage breakdown to stderr, and this is the first flag worth reaching for whenever a capture feels slow:

bash

$ eensh capture --display :1 --time screenshot.png

eensh timing: capture=910us resize=620us encode=3870us base64=330us total=5730us (14907 bytes)

Five numbers, and each answers a different question. If capture dominates, the display or the transfer is the problem. If encode dominates, the codec and the image size are. If total is much larger than the parts, something outside the pipeline is costing you — process startup, most likely.

You now have an image and a document describing it. The document is where the interesting part lives — reading the response takes it apart.

Choosing what to capture

Choosing the image

Choosing where it goes

Asking where the time went

Next