API Reference

A rectangular region on screen defined by corner coordinates.

An (x, y) tuple. swipe takes these; ObjectMatch.center returns one.

Result of a screenshot capture operation.

Result of a template matching operation. x and y are the center of the match.

Result of OCR text recognition.

Android hardware key codes for key_press.

+ NUM_0–NUM_9 for the numeric keypad.

An ImageMap is a read-only object with one ImageRef per declared image, reached by dot access. Any vision call accepts an ImageRef directly. See the Image Library section.

An event fired by a runtime dashboard widget the user interacted with.

Get the current device screen dimensions in pixels. Use it to compute coordinates so the macro survives a resolution change.

Get detailed metadata about the connected device.

A stable UUID for the PC the macro runs on — the same across restarts, shared by every macro on that machine. It is the default machine_id for storage, so you rarely call it directly. Raises RPCError rather than returning an empty string.

Tap at pixel (x, y). delay_ms is a pause after the tap — useful for letting a screen settle. Default 1000 ms; drop to 0 in tight loops.

Drag from one point to another. Both points are (x, y) tuples. duration_ms controls speed: short for a flick, long for a controlled drag.

Type into the currently focused field. Tap the field first to focus it.

Press a hardware key. duration_ms is the hold time — raise it for a long-press.

Capture the screen as an in-memory base64 PNG. The main reason to call this explicitly is to reuse one screenshot across several searches and avoid re-capturing for each.

Find one template on screen. Returns an ObjectMatch or None if nothing matched at or above threshold.

Same parameters as find_object but returns every match, sorted best-confidence first. Default max_matches is 10.

Search for several templates at once — handy when a UI element has variants (themes, languages, states). Takes a list. The returned match's .matched_template_id tells you which one hit.

Block until a template appears, or timeout_ms elapses. The wait happens server-side, so it is more efficient than polling find_object yourself. The right call for "do something, then wait for the next screen".

OCR — read text off the screen. Always pass a region; OCR on a tight box is faster and far more accurate than reading the whole screen.

psm — tells the engine the shape of the text: 7 single line (default), 8 single word, 6 uniform block, 11 scattered text.

Declare your images by name. Returns an ImageMap — a read-only object with one ImageRef per entry. Names must be valid Python identifiers.

Launch an Android app by package name.

Force-stop an app.

Package name of whatever is in the foreground.

How the app is currently running. Compare against the module constants:

True if that app currently has input focus. Good for guarding a tap or typing.

Persist a dict. Re-saving the same key updates the entry. Raises ValueError if data is not JSON-serializable.

Read an entry back, or an empty dict if nothing was stored. The load-or-default pattern is one line.

Every entry for a task name, across all machines and ports. Each item is { "machine_id", "port", "data", "updated_at" }. Use it to roll up results from many emulators running the same macro.

Read the device clipboard as text.

script_args.py parses the command line at import time, so args is ready to use immediately. It is generated — regenerate it from the UI Builder whenever the form changes; do not hand-edit it.

Update a Runtime Label, the caption of a progress bar, a text area, or a button label.

Update a Progress Bar. Studio clamps value to the widget's [min, max].

A chart holds a series of { label, value } points. Stream them as they arrive or replace the dataset at once. series groups points into named lines/bars.

A text area is the natural place for a running log. append_text adds a line and auto-scrolls; lines past maxLines drop off the top.

A table has fixed columns (set in the UI Builder). Rows are dicts whose keys match those column names. Use mas.ui.cell_button(...) inside a cell to get a per-row button.

Model A — blocking. Your script stops and waits for the user. Returns a UIEvent or None on timeout.

Model B — callback. Register handlers, start a background listener, and keep working. The handlers fire on a daemon thread. This is the right model for a Stop or Pause button that must be reactive during a long task.

start_listener() is idempotent and returns immediately. The listener runs on its own RPC connection on a daemon thread. A handler that raises is caught and logged.

Read the current value of a Text Input on demand — no listener required.

Each mas.ui.* call is one round-trip to Studio. Wrap multiple widget updates in batch() to send them as one call — the difference between a smooth dashboard and a flickering one.

batch() blocks cannot be nested. The buffer is process-global — finish the with before letting listener callbacks fire their own updates.

Every SDK error descends from MASError. RPC-level failures are RPCError (with .code, .message, .data).