Python Android Emulator Automation: Getting Started

Macro Automation Studio (MAS) drives Android apps through the screen: it looks at a device, finds what it needs and taps. This page takes you from a fresh install to your first Python macro running on an Android emulator, a cloud device or your phone. It is for first-time users on Windows or Mac.

Before you start

• MAS is installed and you are signed in. See Install MAS.
• You have something to automate on: an Android emulator on this computer, a cloud device, or your own phone. See Devices.
• Your account has an active subscription or the free trial. Every page in the app, apart from sign-in and Subscription, needs one. Without it MAS opens Subscription and stops there. Plans are on the pricing page.

Macro Automation Studio setup: choose a device

A run targets one device. Pick the kind that fits:

To add an emulator:

1. Start the emulator and switch on ADB in its settings. Each emulator guide shows where the setting lives.
2. In MAS, open Device Groups and click Create New Group. Keep the type Local.
3. Open the group and click Add Device.
4. Enter a Device Name and pick the emulator’s port from the Port list. Click Refresh if the list is empty.
5. Click Add Device.

Cloud devices are created on the Cloud Devices page with Create and show up as run targets next to local devices. The phone path is described on the Devices page.

Three ways to get a macro

Run a marketplace bot

1. Open Marketplace and search for the app or game.
2. Open a listing and click Download. The bot appears under Macros, tagged “Downloaded from Marketplace”.
3. In Device Groups, open your group, choose the bot in the device’s Macro selector and click Start.
4. Follow the device card’s Logs tab. Click Stop when you are done.

The full walkthrough with screenshots is How to Run a Macro from the Marketplace. Publishing your own bot is covered on the Marketplace page.

Ask MAS Agent

1. Open Agent and pick a device under Device.
2. Describe the task in plain words and click Author.
3. Answer when the card “The agent needs your input” appears. The agent stops and asks instead of guessing.
4. When the macro passes 3 validation runs, click Add to My Macros.

The result is a normal Python project you can open in the Code Editor. Authoring spends AI credits; running the finished macro costs none. Read more on the MAS Agent page.

Write Python for Android emulator automation

1. Open Macros and click Create New Project.
2. Choose Code-Based, set Target Device to mobile, name the project and click Create Project.
3. Open the project. The Code Editor shows src/app.py. Paste the script below.
4. Pick your device and click Run (F5). Stop is Shift+F5 and Save is Ctrl+S.

The SDK overview explains the namespaces; the API reference lists every function.

Your first script

This script reads the device, takes a screenshot and runs OCR over the whole screen. Nothing on the device changes.

import mas

device = mas.get_device_info()
print(f"Connected to: {device.name}")

screen = mas.get_screen_size()
print(f"Screen: {screen.width}x{screen.height}")

shot = mas.take_screenshot()
print(f"Screenshot: {shot.width}x{shot.height}")

result = mas.read_text()
print(f"Screen text: {result.text[:100]}")

mas.log("First script finished")

mas.log writes a leveled line to the run console. Plain print works as well.

Common patterns

Find an image and tap it

Crop the button in Asset Lab so it lands in your Image Library with an ID, then declare it with mas.images. find_object_retry looks up to three times, two seconds apart, and returns None when nothing matches.

import mas

images = mas.images({"play_button": 42})

match = mas.find_object_retry(images.play_button, total_tries=3, time_sleep=2.0)
if match:
    mas.click(match.x, match.y, delay_ms=1000)
else:
    mas.log("Play button not found", level="warning")

find_object matches at a threshold of 0.8 by default. click waits 1000 ms after the tap so the app can react; lower delay_ms in tight loops.

Read text from a region

import mas
from mas import Region

score = mas.read_text(region=Region(x1=800, y1=10, x2=1050, y2=60), psm=7)
if score.text.strip().isdigit():
    print(f"Current score: {int(score.text)}")

psm=7 treats the region as a single line, which suits counters. Draw the region in Asset Lab and test it live before you copy the coordinates.

Handle errors

import mas

try:
    match = mas.find_object_retry(42)
    if match:
        mas.click(match.x, match.y)
except mas.DeviceNotConnectedError:
    mas.log("No device connected", level="error")
except mas.ImageNotFoundError:
    mas.log("Image ID is not in your library", level="error")
except mas.TimeoutError:
    mas.log("The device did not answer in time", level="error")
except mas.RPCError as e:
    mas.log(f"RPC error: {e}", level="error")

Troubleshooting

Could not discover RPC port

The script was started outside MAS, or the app is not running. Run scripts from the Code Editor or from a device card; the app launches them with the connection details.

The app opens Subscription instead of the page I clicked

Your entitlement is missing or has lapsed. Start the trial or pick a plan, then go back. See Billing.

Device not found or stuck on Connecting

The emulator’s ADB is off, the emulator is still booting, or it listens on another port. See ADB troubleshooting.