# Python Android Emulator Automation: Getting Started

> Set up Python Android emulator automation in Macro Automation Studio: connect a device, then run a marketplace bot, ask MAS Agent or write a first macro.

Source: https://automationmacro.com/docs/getting-started (Start, updated 2026-09-04)

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](/docs/install).
- You have something to automate on: an Android emulator on this computer, a cloud device, or your own phone. See [Devices](/docs/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](/pricing).

> [!NOTE]
> The Python SDK is already installed. MAS ships its own Python 3.13 environment with the `mas` package, so `import mas` works in the Code Editor with no setup on your side.

## Macro Automation Studio setup: choose a device

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

| Device | Where it runs | Good for |
|---|---|---|
| Emulator (BlueStacks, LDPlayer, MuMu Player, MEmu) | On this computer, over adb | First steps and local testing |
| Cloud device | In MAS's cloud, streamed to the app over WebRTC | Runs that continue with your computer off |
| Your own phone | On this computer, over adb (advanced) | Apps that only behave on real hardware |

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](/docs/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](/docs/run-macro-from-marketplace). Publishing your own bot is covered on the [Marketplace](/docs/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](/docs/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** (<kbd>F5</kbd>). **Stop** is <kbd>Shift</kbd>+<kbd>F5</kbd> and **Save** is <kbd>Ctrl</kbd>+<kbd>S</kbd>.

The [SDK overview](/docs/sdk) explains the namespaces; the [API reference](/docs/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.

```python
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.

```python
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

```python
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

```python
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](/docs/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](/docs/adb-troubleshooting).