# Android エミュレータを Python で自動操作: 入門ガイド

> Macro Automation Studio で Android エミュレータを Python で自動操作する入門。デバイスを接続し、Marketplace の bot を動かすか、MAS Agent に頼むか、最初のマクロを書きます。

Source: https://automationmacro.com/ja/docs/getting-started (はじめに, updated 2026-09-05)

Macro Automation Studio (MAS) は、画面を通して Android アプリを自動操作します。デバイスの画面を見て、必要なものを見つけ、タップします。このページでは、インストール直後の状態から、Android エミュレータ、クラウドデバイス、またはお手持ちのスマホで最初の Python マクロを動かすところまでを案内します。Windows または Mac で初めて使う方向けです。

## 始める前に

- MAS がインストール済みで、サインインしていること。[MAS のインストール](/docs/install) を参照してください。
- 自動化の対象があること: このコンピューター上の Android エミュレータ、クラウドデバイス、またはお手持ちのスマホ。[デバイス](/docs/devices) を参照してください。
- アカウントに有効なサブスクリプションか無料トライアルがあること。アプリ内のページは、サインインと **サブスクリプション** 以外すべて、これを必要とします。ない場合、MAS は **サブスクリプション** を開いてそこで止まります。プランは [料金ページ](/pricing) にあります。

> [!NOTE]
> Python SDK はすでにインストールされています。MAS は `mas` パッケージ入りの独自の Python 3.13 環境を同梱しているので、Code Editor では何も設定せずに `import mas` が動きます。

## Macro Automation Studio の設定: デバイスを選ぶ

1 回の実行は 1 台のデバイスを対象にします。用途に合う種類を選んでください。

| デバイス | 動く場所 | 向いている用途 |
|---|---|---|
| エミュレータ (BlueStacks、LDPlayer、MuMu Player、MEmu) | このコンピューター上、adb 経由 | 最初の一歩とローカルでのテスト |
| クラウドデバイス | MAS のクラウド上、WebRTC でアプリに配信 | コンピューターを切っても続く実行 |
| お手持ちのスマホ | このコンピューター上、adb 経由 (上級者向け) | 実機でしか正しく動かないアプリ |

エミュレータを追加するには:

1. エミュレータを起動し、その設定で ADB をオンにします。設定の場所は各エミュレータのガイドにあります。
2. MAS で **デバイスグループ** を開き、**新しいグループを作成** をクリックします。種類は **ローカル** のままにします。
3. グループを開き、**デバイスを追加** をクリックします。
4. **デバイス名** を入力し、**ポート** の一覧からエミュレータのポートを選びます。一覧が空なら **更新** をクリックします。
5. **デバイスを追加** をクリックします。

クラウドデバイスは **クラウドデバイス** ページの **作成** で作り、ローカルデバイスと並んで実行対象に表示されます。スマホを使う手順は [デバイス](/docs/devices) ページで説明しています。

## マクロを手に入れる 3 つの方法

### Marketplace の bot を実行する

1. **Marketplace** を開き、アプリやゲームを検索します。
2. 一覧の項目を開き、**ダウンロード** をクリックします。bot は **マクロ** に「Marketplace からダウンロード」のタグ付きで表示されます。
3. **デバイスグループ** でグループを開き、デバイスの **マクロ** セレクターで bot を選んで **開始** をクリックします。
4. デバイスカードの **ログ** タブを追いかけます。終わったら **停止** をクリックします。

スクリーンショット付きの詳しい手順は [Marketplace からマクロを実行する方法](/docs/run-macro-from-marketplace) にあります。自作 bot の公開は [Marketplace](/docs/marketplace) ページで説明しています。

### MAS Agent に依頼する

1. **エージェント** を開き、**デバイス** で対象を選びます。
2. やりたいことを普通の文章で書き、**作成** をクリックします。
3. 「エージェントが入力を必要としています」のカードが出たら答えます。エージェントは推測せず、止まって質問します。
4. マクロが 3 回の検証実行に合格したら、**マイマクロに追加** をクリックします。

結果は Code Editor で開ける普通の Python プロジェクトです。作成には AI クレジットを使いますが、完成したマクロの実行にはかかりません。詳しくは [MAS Agent](/docs/agent) ページをお読みください。

### Android エミュレータを自動操作する Python を書く

1. **マクロ** を開き、**新しいプロジェクトを作成** をクリックします。
2. **コードベース** を選び、**対象デバイス** をモバイルにし、プロジェクト名を付けて **プロジェクトを作成** をクリックします。
3. プロジェクトを開きます。Code Editor に `src/app.py` が表示されます。下のスクリプトを貼り付けます。
4. デバイスを選んで **実行** (<kbd>F5</kbd>) をクリックします。**停止** は <kbd>Shift</kbd>+<kbd>F5</kbd>、**保存** は <kbd>Ctrl</kbd>+<kbd>S</kbd> です。

[SDK 概要](/docs/sdk) で名前空間を説明し、[API リファレンス](/docs/api-reference) にすべての関数を載せています。

## 最初のスクリプト

このスクリプトはデバイス情報を読み、スクリーンショットを撮り、画面全体に OCR をかけます。デバイス上では何も変わりません。

```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` はレベル付きの 1 行を実行コンソールに書きます。普通の `print` も使えます。

## よく使うパターン

### 画像を見つけてタップする

Asset Lab でボタンを切り出すと、ID 付きで画像ライブラリに入ります。それを `mas.images` で宣言します。`find_object_retry` は 2 秒間隔で最大 3 回探し、何も一致しなければ `None` を返します。

```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` は既定でしきい値 0.8 で照合します。`click` はタップ後にアプリが反応できるよう 1000 ms 待ちます。短いループでは `delay_ms` を下げてください。

### 領域から文字を読む

```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` は領域を 1 行として扱うので、カウンターに向いています。座標をコピーする前に、Asset Lab で領域を描いてライブでテストしてください。

### エラーを処理する

```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")
```

## トラブルシューティング

### Could not discover RPC port

スクリプトが MAS の外で起動されたか、アプリが動いていません。スクリプトは Code Editor かデバイスカードから実行してください。アプリが接続情報を渡して起動します。

### クリックしたページではなくサブスクリプションが開く

利用資格がないか、期限が切れています。トライアルを始めるかプランを選んでから戻ってください。[お支払い](/docs/billing) を参照してください。

### デバイスが見つからない、または Connecting のまま止まる

エミュレータの ADB がオフ、エミュレータがまだ起動中、または別のポートで待ち受けています。[ADB トラブルシューティング](/docs/adb-troubleshooting) を参照してください。