이미지 인식 매크로 원리: MAS 작동 방식

Macro Automation Studio(MAS)는 사람이 하는 방식 그대로 Android 앱을 자동화합니다. 화면을 보고, 판단하고, 탭합니다. 이 페이지는 이미지 인식 매크로가 어떻게 동작하는지, 앱에서 만나는 용어가 무엇을 뜻하는지, 각 부분이 어디서 실행되는지 설명합니다. 한 번 읽어 두면 나머지 문서가 훨씬 쉽게 이해됩니다.

이미지 인식 매크로가 화면을 보는 방법

MAS는 APK를 수정하지 않고 앱 메모리도 읽지 않습니다. adb를 통해 바깥에서, 세 가지 구성 요소로 동작합니다.

템플릿 이미지

템플릿은 화면의 작은 조각입니다: 버튼, 아이콘, 배지. Asset Lab에서 실제 기기 화면을 잘라 만들면 Image Library에 숫자 ID와 함께 저장되고, 스크립트는 그 ID로 참조합니다. 실행 시 find_object가 새 스크린샷을 찍어 OpenCV 템플릿 매칭으로 템플릿을 찾습니다. 기본적으로 유사도 0.8(threshold=0.8) 이상이어야 일치로 보며, 중심점을 반환하므로 다음 줄에서 바로 탭할 수 있습니다.

이미지 파일은 jpg, png, gif, webp를 쓸 수 있고 각각 최대 10 MB입니다. 템플릿은 작고 구별되게 만드세요. 화면 전체는 정확히 그 화면에서만 일치하지만, 버튼 하나는 버튼이 나타나는 곳 어디서든 일치합니다.

Android에서의 OCR 자동화

텍스트는 read_text를 통해 Tesseract OCR로 읽습니다. Region(x1, y1, x2, y2)를 넘겨 엔진이 화면 전체가 아니라 카운터 하나, 레이블 하나만 보게 하고, 페이지 분할 모드(psm=7은 한 줄, 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에 묶이므로, 매크로를 실행하는 모든 기기를 만들 때와 같은 해상도로 유지하세요. 에뮬레이터 가이드마다 권장 크기가 있고, 클라우드 기기는 고정된 디스플레이 프리셋으로 만들어집니다.

용어

실행 위치

세 곳에서 작업이 이루어지며, 지금 보고 있는 것이 어느 쪽인지 알아 두면 좋습니다.

에뮬레이터는 내 컴퓨터가 조작

PC나 Mac의 MAS가 프로세스 이름과 수신 포트로 에뮬레이터를 찾은 뒤 adb connect 127.0.0.1:<port>로 각각 통신합니다. 로컬 기기의 스크린샷, 탭, OCR은 모두 내 컴퓨터에서 처리되므로 매크로가 실행되는 동안 앱을 열어 두어야 합니다. 스케줄러도 마찬가지입니다.

클라우드 기기는 MAS 클라우드에서 실행

클라우드 기기는 MAS 서버에 있습니다. 여기서 매크로를 실행하면 MAS가 프로젝트 스냅샷을 올려 기기 옆에서 실행합니다. 앱에서 화면을 실시간으로 볼 수도 있고 앱을 완전히 닫아도 됩니다. 어느 쪽이든 실행은 계속됩니다. 유휴 기기는 약 1시간 동안 활동이 없으면 정지하며 데이터는 유지합니다.

스크립트는 JSON-RPC로 앱과 통신

매크로는 일반 파이썬 프로세스입니다. 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 크레딧을 씁니다. 결과물인 매크로는 일반 파이썬이며, 에이전트 없이 다른 매크로와 똑같이 에뮬레이터나 클라우드 기기에서 실행됩니다.

구독

로그인과 Subscription을 제외한 앱의 모든 페이지에는 활성 이용 권한이 필요합니다: 무료 체험 또는 유료 요금제. 요금제는 기기 수, 즉 본인의 에뮬레이터나 휴대폰 몇 대를 동시에 실행할 수 있는지로 정해집니다. 클라우드 기기는 자체 월간 크레딧이 포함된 추가 옵션이며, 에이전트 세션용 크레딧은 추가 충전할 수 있습니다. 해지해도 결제된 기간이 끝날 때까지는 이용할 수 있습니다. 동작 방식은 결제 페이지에, 금액은 가격 페이지에 있습니다.

다음 단계

기기 페이지에서 기기를 설정하거나, Asset Lab에서 첫 템플릿을 자르거나, 코드부터 시작하고 싶다면 SDK 개요를 읽어 보세요.