画像認識マクロの仕組み: MAS の基本概念

Macro Automation Studio (MAS) は、人がやるのと同じ方法で Android アプリを自動化します。画面を見て、判断し、タップします。このページでは、画像認識マクロの仕組み、アプリで出会う用語、そして各部分がどこで動くかを説明します。一度読めば、残りのドキュメントが理解しやすくなります。

画像認識マクロが画面を見る仕組み

MAS は APK を改変せず、アプリのメモリも読みません。adb を通して外側から、3 つの部品で動きます。

テンプレート画像

テンプレートとは画面の小さな切り抜きです: ボタン、アイコン、バッジなど。Asset Lab でライブのデバイス画面から切り出すと、数値の ID 付きで画像ライブラリに入り、スクリプトはその ID で参照します。実行時に find_object が新しいスクリーンショットを撮り、OpenCV のテンプレートマッチングでその中からテンプレートを探します。一致には既定で 0.8 の類似度 (threshold=0.8) が必要で、中心点を返すので、次の行でタップできます。

画像ファイルは jpg、png、gif、webp で、1 枚 10 MB までです。テンプレートは小さく特徴的にしてください。画面全体はその画面だけにしか一致しませんが、ボタンならボタンが出る場所ならどこでも一致します。

Android での OCR 自動化

文字は read_text を通して Tesseract OCR で読みます。Region(x1, y1, x2, y2) を渡すと、画面全体ではなく 1 つのカウンターや 1 つのラベルだけを見るようになり、ページセグメンテーションモード (1 行なら psm=7、1 語なら psm=8) も指定できます。ColorConversion.BLACK_WHITE は、ノイズの多い背景上の色付き文字に役立ちます。Asset Lab にはライブの OCR テストがあるので、コードに入れる前に領域を調整できます。

人間らしい入力

入力は本物のタッチイベントとキーイベントとして送られます: click、swipe、input_text、key_press、zoom_in、zoom_out。タイミングは自由に設定できます。click はタップ後に delay_ms=1000 待ち、swipe は duration_ms=1000 かけて動き、500 ms 以上押したキーは長押しになります。ゆっくり、間隔を空けたマクロほど機械的に見えません。

座標と画面サイズ

すべての座標は画面左上からのピクセルオフセットです。get_screen_size() は幅と高さを、get_device_info() はそれに加えてデバイス名を返します。テンプレートと領域は、取り込んだときの解像度と DPI に結び付いています。マクロを動かすすべてのデバイスを、作ったときと同じ解像度にしてください。各エミュレータのガイドで推奨サイズを示しており、クラウドデバイスは固定のディスプレイプリセットで作成されます。

用語

動く場所

作業は 3 つの場所で行われます。今どれを見ているかを知っておくと役立ちます。

あなたのコンピューターがエミュレータを操作する

PC や Mac 上の MAS は、プロセス名と待ち受けポートでエミュレータを見つけ、それぞれと adb connect 127.0.0.1:<port> で通信します。ローカルデバイスのスクリーンショット、タップ、OCR はすべてあなたのマシン上で行われるため、マクロの実行中はアプリを開いたままにする必要があります。スケジューラーも同じです。

クラウドデバイスは MAS のクラウドで動く

クラウドデバイスは MAS のサーバー上にあります。そこでマクロを実行すると、MAS がプロジェクトのスナップショットをアップロードし、デバイスの隣で実行します。アプリで画面をライブで見ることも、アプリを完全に閉じることもできます。どちらでも実行は続きます。アイドル状態のデバイスは約 1 時間の無操作で停止し、データは保持されます。

スクリプトは JSON-RPC でアプリと通信する

マクロは普通の Python プロセスです。MAS は独自の Python 3.13 環境内で python -u -m src.app として起動し、接続情報を環境変数 (MAS_RPC_PORT、MAS_RPC_HOST、MAS_DEVICE_ID、MAS_SESSION_TOKEN) で渡します。すべての mas.* 呼び出しは、ローカルソケット経由の JSON-RPC 2.0 リクエストです。アプリが adb、OpenCV、Tesseract を持ち、結果を返します。クラウドデバイスでは同じ呼び出しがサンドボックス内の unix ソケットを通ります。これが、import mas にインストールが不要な理由であり、MAS の外で起動したスクリプトが「Could not discover RPC port」と報告する理由です。

AI は作成時だけ、実行時には使わない

MAS Agent は探索とコンパイルの間に AI クレジットを使います。生成されるマクロは素の Python で、他のマクロと同じように、エミュレータでもクラウドデバイスでも、エージェントを介さずに動きます。

サブスクリプション

アプリ内のページは、サインインと サブスクリプション を除いてすべて、有効な利用資格 (無料トライアルか有料プラン) を必要とします。プランの大きさはデバイス数で決まります。つまり、自分のエミュレータやスマホを同時に何台動かせるかです。クラウドデバイスは月ごとのクレジット付きのアドオンで、エージェントのセッション用にクレジットを追加購入できます。解約しても支払い済み期間の終わりまで利用できます。仕組みは お支払い ページに、金額は 料金ページ にあります。

次に読むもの

デバイス ページでデバイスを設定するか、Asset Lab で最初のテンプレートを切り出すか、コードから始めたければ SDK 概要 をお読みください。