Docs API Reference

API Reference

Complete documentation for every function in the MAS Python SDK.

Note: Device connection is handled automatically by MAS. Scripts do not need to explicitly connect or disconnect — the device is pre-configured when your script runs.

Types

Region

dataclass

A rectangular region on screen defined by corner coordinates.

from mas import Region
region = Region(x1=100, y1=200, x2=900, y2=260)

Field	Type	Description
x1	int	Left edge x-coordinate (pixels from left)
y1	int	Top edge y-coordinate (pixels from top)
x2	int	Right edge x-coordinate (pixels from left)
y2	int	Bottom edge y-coordinate (pixels from top)

Screenshot

dataclass

Result of a screenshot capture operation.

Field	Type	Description
base64	str	Base64-encoded PNG image data
width	int	Screenshot width in pixels
height	int	Screenshot height in pixels
timestamp	str	Capture timestamp in ISO 8601 format

ObjectMatch

dataclass

Result of a template matching operation.

Field	Type	Description
x	int	Center x coordinate
y	int	Center y coordinate
center	tuple[int, int]	Property returning (x, y) tuple

TextRecognitionResult

dataclass

Result of OCR text recognition.

Field	Type	Description
text	str	Extracted text
confidence	float	Recognition confidence (0.0 to 1.0)
region	Region	Region where text was found
language	str	Language code used for recognition

KeyCode

enum

Android hardware key codes.

BACK Back

HOME Home

MENU Menu

ENTER Enter

DELETE Delete

SPACE Space

POWER Power

VOLUME_UP Vol Up

VOLUME_DOWN Vol Down

DPAD_UP D-Pad Up

DPAD_DOWN D-Pad Down

DPAD_LEFT D-Pad Left

+ TAB, APP_SWITCH, CAMERA, MEDIA_PLAY, MEDIA_PAUSE, NUM_0–NUM_9, and more.

Device Control

`mas.get_screen_size()` ScreenSize

Get the current device screen dimensions.

size = mas.get_screen_size()
print(f"{size.width}x{size.height}")

`mas.get_device_info()` DeviceInfo

Get detailed information about the connected device.

info = mas.get_device_info()
print(f"{info.name} ({info.type})")

User Interaction

`mas.click(x, y, delay_ms=100)` None

Click at the specified coordinates.

Param	Type	Default	Description
x	int	required	Horizontal position (pixels from left)
y	int	required	Vertical position (pixels from top)
delay_ms	int	100	Delay after click in milliseconds

mas.click(150, 300)
mas.click(150, 300, delay_ms=500)

`mas.swipe(from_coords, to_coords, duration_ms=500)` None

Perform a swipe gesture from one point to another.

Param	Type	Default	Description
from_coords	tuple[int, int]	required	Starting (x, y) coordinates
to_coords	tuple[int, int]	required	Ending (x, y) coordinates
duration_ms	int	500	Swipe duration in milliseconds

# Scroll down
mas.swipe((500, 1500), (500, 500), duration_ms=400)

`mas.input_text(text, delay_ms=0)` None

Type text into the currently focused input field.

Param	Type	Default	Description
text	str	required	Text to input
delay_ms	int	0	Delay after typing in milliseconds

mas.click(150, 200) # Focus input first
mas.input_text("user@example.com")

`mas.key_press(key_code, modifiers=None, duration_ms=100)` None

Press a hardware key or key combination.

Param	Type	Default	Description
key_code	KeyCode	required	Key to press (from KeyCode enum)
modifiers	list[Modifier] \| None	None	Modifier keys (Shift, Ctrl, Alt, Meta)
duration_ms	int	100	Duration to hold the key

mas.key_press(KeyCode.BACK)
mas.key_press(KeyCode.POWER, duration_ms=3000) # Long press

Computer Vision

`mas.take_screenshot()` Screenshot

Capture the current device screen as a base64-encoded image.

screenshot = mas.take_screenshot()
# Reuse for multiple searches
btn = mas.find_object(123, screenshot=screenshot)
icon = mas.find_object(456, screenshot=screenshot)

`mas.find_object(image_id, ...)` ObjectMatch | None

Find an image on screen using template matching.

Param	Type	Default	Description
image_id	int	required	ID of the template image from your Image Library
threshold	float	0.8	Match confidence threshold (0.0 to 1.0)
screenshot	Screenshot \| None	None	Optional screenshot to reuse
continuous_mode	bool	False	Keep searching until timeout or found
timeout_ms	int	1000	Timeout in milliseconds

match = mas.find_object(123)
if match: mas.click(*match.center)

`mas.find_any_object(image_ids, ...)` ObjectMatch | None

Find the first matching image from a list of templates.

Param	Type	Default	Description
image_ids	list[int]	required	List of image IDs to search for
search_strategy	str	"first_match"	"first_match", "best_match", or "priority_order"

# Try multiple button variants
result = mas.find_any_object([123, 124, 125])

`mas.read_text(region=None, language="eng", ...)` TextRecognitionResult

Extract text from screen using OCR.

Param	Type	Default	Description
region	Region \| None	None	Screen region to read from (full screen if None)
language	str	"eng"	Language code for OCR
text_filter	str	"none"	"none", "integerOnly", "floatOnly", "alphanumeric", "pattern"
filter_pattern	str \| None	None	Regex pattern when text_filter is "pattern"

result = mas.read_text(text_filter="integerOnly")
score = int(result.text) if result.text else 0

`mas.wait_for_object(image_id, timeout_ms=10000, threshold=0.8)` ObjectMatch | None

Wait for an image to appear on screen (server-side polling).

home = mas.wait_for_object(200, timeout_ms=30000)
if home: mas.click(*home.center)

App Management

`mas.open_app(package_name, timeout_ms=2000)` None

Launch an Android application by package name.

mas.open_app("com.android.chrome")
mas.open_app("com.instagram.android", timeout_ms=5000)

`mas.close_app(package_name)` None

Force stop an Android application.

mas.close_app("com.instagram.android")

`mas.get_current_app()` str

Get the package name of the currently active application.

current = mas.get_current_app()
if "launcher" in current.lower():
mas.open_app("com.example.app")

Exceptions

The SDK provides a hierarchy of exceptions for error handling.

MASError (base)

RPCError

|-- ConnectionError

|-- ParseError (-32700)

|-- InvalidRequestError (-32600)

|-- MethodNotFoundError (-32601)

|-- InvalidParamsError (-32602)

|-- InternalError (-32603)

|-- DeviceNotConnectedError (-32001)

|-- DeviceNotFoundError (-32002)

|-- CommandFailedError (-32003)

|-- ImageNotFoundError (-32004)

|-- TimeoutError (-32005)

RPCError Attributes

code	int	JSON-RPC error code
message	str	Human-readable error message
data	Any \| None	Optional additional error data

API Reference

Types

Region

Screenshot

ObjectMatch

TextRecognitionResult

KeyCode

Device Control

mas.get_screen_size() ScreenSize

mas.get_device_info() DeviceInfo

User Interaction

mas.click(x, y, delay_ms=100) None

mas.swipe(from_coords, to_coords, duration_ms=500) None

mas.input_text(text, delay_ms=0) None

mas.key_press(key_code, modifiers=None, duration_ms=100) None

Computer Vision

mas.take_screenshot() Screenshot

mas.find_object(image_id, ...) ObjectMatch | None

mas.find_any_object(image_ids, ...) ObjectMatch | None

mas.read_text(region=None, language="eng", ...) TextRecognitionResult

mas.wait_for_object(image_id, timeout_ms=10000, threshold=0.8) ObjectMatch | None

App Management

mas.open_app(package_name, timeout_ms=2000) None

mas.close_app(package_name) None

mas.get_current_app() str

Exceptions

RPCError Attributes

`mas.get_screen_size()` ScreenSize

`mas.get_device_info()` DeviceInfo

`mas.click(x, y, delay_ms=100)` None

`mas.swipe(from_coords, to_coords, duration_ms=500)` None

`mas.input_text(text, delay_ms=0)` None

`mas.key_press(key_code, modifiers=None, duration_ms=100)` None

`mas.take_screenshot()` Screenshot

`mas.find_object(image_id, ...)` ObjectMatch | None

`mas.find_any_object(image_ids, ...)` ObjectMatch | None

`mas.read_text(region=None, language="eng", ...)` TextRecognitionResult

`mas.wait_for_object(image_id, timeout_ms=10000, threshold=0.8)` ObjectMatch | None

`mas.open_app(package_name, timeout_ms=2000)` None

`mas.close_app(package_name)` None

`mas.get_current_app()` str