Capture

Set the capture region

Steers VisionPiper's one stored capture region (vision_region_set). Supply exactly one of:

  • a rect: all four of x, y, width, height, in space (display = points from the target display's top-left, the default; global = global points with the main display at the origin);
  • a named target: window_title and/or bundle_id (a window), selector (an accessibility element, optionally scoped by bundle_id) or description (something to find on screen);
  • pick: true, which opens VisionPiper's drag-to-select overlay and waits for the user.

An explicit rect outranks a named target and the overlay. VisionPiper stays the region's owner: it trims an overhang, and the applied rect it reports is what the response carries. Every refusal rides the precondition_failed envelope with a typed reason: visionpiper_unavailable, screen_recording_denied, invalid_region, unknown_display, selection_cancelled, selection_timed_out, or a named-target resolver reason such as window_not_found. Tolerate unknown reasons.

post/v1/vision/region

Request

  • Base URL: http://localhost:9998
  • URL: http://localhost:9998/v1/vision/region
  • Auth: HTTP bearer

Request body

xnumber double
ynumber double
widthnumber double

At least 1 point.

heightnumber double

At least 1 point.

space'display' | 'global'

Coordinate space of the rect. Defaults to display.

display_idinteger

CGDirectDisplayID from system_display_list. With space=display it names the target display (default is VisionPiper's main display); with space=global it is the preferred display when the rect overlaps it.

window_titlestring

Title of a window to take the region from.

bundle_idstring

Bundle id of the app whose window (or, with selector, whose element) supplies the region.

selectorstring

Accessibility selector of an element whose frame becomes the region.

descriptionstring

A description of something on screen to find and use as the region.

pickboolean

Open VisionPiper's drag-to-select overlay and wait for the user.

Response

Region applied (status is region_set)

status'ready' | 'no_region' | 'region_set' required
generationinteger required

Region generation; moves every time the region changes.

recordingboolean required

Whether a recording is running.

selection_pendingboolean required

Whether the drag-to-select overlay is waiting for the user.

display_idinteger

CGDirectDisplayID the region sits on.

indicator_visibleboolean

Whether the region's border indicator is showing.

Changes

No recorded changes to this operation across all 1 revision of this API.