# MuMu Player 12 ADB 포트 확인과 MAS 연결 설정

> MuMu Player 12의 ADB 포트를 찾아 Macro Automation Studio에 연결하고, 모든 인스턴스를 기기로 추가하며, 조작 녹화 대신 MAS 매크로를 실행하는 방법을 설명합니다.

Source: https://automationmacro.com/ko/docs/mumu-setup-guide (기기, updated 2026-09-05)

이 가이드는 MuMu Player 12 ADB 포트를 찾아 인스턴스를 Macro Automation Studio(MAS)에 연결하는 방법과, MAS 매크로가 MuMu의 Operation Recording과 어떻게 다른지 설명합니다. MuMu Player 12 ADB 포트 확인 절차는 Windows 기준이며, Mac 빌드는 짧은 절에서 다룹니다.

## 시작하기 전에

- Windows 10 또는 11, 또는 Apple Silicon Mac에 MAS가 설치되어 있고 로그인한 상태. 체험용 MAS는 [다운로드 페이지](/download)에서 무료로 받을 수 있습니다.
- [mumuplayer.com](https://www.mumuplayer.com/)에서 MuMu Player 12를 설치하고 한 번 실행한 상태.
- 인스턴스가 Android 홈 화면까지 완전히 부팅된 상태.
- 자동화할 앱이 MuMu Player 안에 설치되어 있고 로그인된 상태.

## 1. MuMu Player 12 설치

1. 공식 사이트에서 MuMu Player 12를 받아 설치 프로그램을 실행합니다.
2. MuMu Player를 시작하고 홈 화면을 기다립니다.
3. MAS에 기기를 추가하기 전에 자동화할 앱을 설치하고 로그인합니다.

## 2. 고정 해상도 설정

MAS는 템플릿 이미지를 픽셀 단위로 비교하므로 해상도를 한 번 정하고 유지하세요.

1. MuMu Player 창 오른쪽 위의 **Settings**를 클릭합니다.
2. **Display**를 열고 사용자 지정 해상도를 고릅니다.
3. 너비 540, 높이 960, DPI 240을 입력합니다. 이것이 MAS 기준선입니다. 직접 쓴 매크로는 Asset Lab에서 캡처한 해상도를 기대합니다.
4. 저장하고 MuMu Player가 요청하면 인스턴스를 다시 시작합니다.

> [!WARNING]
> 템플릿을 캡처한 뒤 해상도를 바꾸면 모든 매칭 위치가 어긋납니다. MuMu 자체 녹화기에도 같은 규칙이 적용됩니다.

## 3. MuMu Player 12에서 ADB 켜기

공식 ADB 안내에는 MuMu Player 12용 토글이 없습니다. 실행 중인 인스턴스는 별도 설정 없이 자기 포트에서 adb에 응답하므로, 필요한 것은 포트 번호입니다:

- 인스턴스 하나라면 창 오른쪽 위의 메뉴를 열고 **Issues Diagnostic**을 선택합니다. ADB 디버깅 포트가 거기에 표시됩니다.
- 인스턴스 여러 개라면 **MuMuPlayer Multi-instance 12**를 열고 실행 중인 인스턴스의 ADB 아이콘을 클릭해 포트를 확인합니다.

## 4. MuMu Player ADB 포트와 MAS의 스캔 방식

MuMu Player 12는 주 인스턴스에 포트 **16384**를 주고, 추가 인스턴스마다 32씩 더합니다: 16416, 16448 등. 포트가 사용 중이면 MuMu가 1을 더하므로 16385가 나올 수도 있습니다. MAS는 에뮬레이터를 찾기 위해 `adb devices`를 쓰지 않습니다. 실행 중인 프로세스를 스캔해 다음 조건이 모두 맞는 포트만 남깁니다:

- 프로세스 이름에 `nemuheadless` 또는 `mumu`가 들어 있습니다.
- 포트가 16384에서 16576 사이, 26624에서 27264 사이, 정확히 7555, 또는 5555에서 5599 사이의 홀수입니다.
- 소켓이 `127.0.0.1`, `0.0.0.0` 또는 모든 인터페이스에서 수신합니다.

16384에서 16576 범위는 주 인스턴스와 그다음 여섯 개를 다룹니다. 7555와 5555 범위는 이전 MuMu 버전에서 온 것입니다. 조건에 맞는 포트는 **Add New Device** 대화 상자에 `MuMu` 레이블로 나타납니다. 예를 들어 `16384 - MuMu`입니다. MAS는 기기 그룹을 열 때와 **Refresh**를 클릭할 때마다 스캔합니다.

## 5. MAS에서 MuMu Player ADB 연결

1. 사이드바에서 **Device Groups**를 열고 그룹을 열거나 새로 만듭니다.
2. **Add Device**를 클릭합니다.
3. 최대 50자의 **Device Name**을 입력합니다.
4. **Port**에서 이 인스턴스의 `MuMu` 항목을 고릅니다. 목록이 비어 있으면 **Refresh**를 클릭합니다.
5. **Issues Diagnostic**에 표시된 포트가 위 규칙에 맞지 않으면 **Custom Port**를 선택하고 입력합니다. MAS는 1024부터 65535까지 받습니다.
6. 필요하면 **Startup Macro**를 고릅니다.
7. **Add Device**를 클릭한 뒤 기기 카드에서 **Start**를 클릭합니다.

카드가 **Connecting**을 거쳐 **Running**으로 바뀝니다. MAS는 자체 adb 서버를 시작하고, `127.0.0.1:<port>`의 오래된 항목을 제거한 뒤, 그 주소로 `adb connect`를 실행합니다.

## MuMu Player의 매크로

MuMu의 **Operation Recording**은 탭을 녹화해 파일에서 재생하며, 세 가지 정지 조건(**Execute x times to stop**, **Execute xx time to stop**, **Infinite loop to manual stop**)과 **Cycle interval**이 있습니다. 재생 시 해상도가 녹화 때와 같아야 한다고 공식 문서가 경고합니다. 파일은 화면을 보지 않고 고정 좌표를 재생하므로, 느린 로딩, 팝업, 위치가 바뀐 버튼이 순서를 깨뜨리고, MuMu Player 안에서만 실행됩니다.

MAS 매크로는 행동하기 전에 화면을 확인하는 파이썬 스크립트입니다. 템플릿 매칭으로 버튼을 찾고, OCR로 텍스트를 읽고, 재시도로 기다리고, 본 것에 따라 분기합니다. MAS가 모든 기기를 adb로 조작하므로 같은 스크립트가 MuMu Player, 다른 에뮬레이터, 클라우드 기기에서 수정 없이 실행됩니다.

- 녹화를 화면 인식 매크로로 다시 만들려면 [이미지 인식 매크로](/docs/guides/image-recognition-macros)를 따라 하세요.
- 조건이 충족될 때까지 반복하거나 예약 실행하려면 [반복, 정지 조건, 예약 실행](/docs/guides/loops-and-scheduling)을 읽어 보세요.

> [!NOTE]
> MAS에서 기기를 시작하기 전에 실행 중인 Operation Recording을 끝내세요. 둘 다 같은 화면에 입력을 보내 서로 방해합니다.

## 여러 MuMu 인스턴스

오른쪽 위의 도구 상자 아이콘에서 **MuMuPlayer Multi-instance 12**를 엽니다. **+New**가 인스턴스를 만들고 **Device setting**이 성능과 디스플레이를 정하므로, 모든 인스턴스에 같은 해상도를 주세요. 인스턴스마다 이전 것보다 32 큰 자기 포트로 수신합니다. 같은 기기 그룹에 각각 별도 기기로 추가하고, 기기별로 매크로와 설정 프로필을 지정한 뒤, 그룹의 **Start All**과 **Stop All**을 사용하세요. 여덟 번째 인스턴스부터는 포트가 16576을 넘어 MAS 목록에 더 이상 나타나지 않으므로 **Custom Port**로 추가하세요. 기기별 인수와 프록시는 [기기 그룹](/docs/device-groups)을 참고하세요.

## Mac에서의 MuMu Player

MuMu는 Apple Silicon Mac용 빌드도 제공합니다. 공식 안내에 따르면 거기서는 ADB가 메뉴 바에 있습니다. 기기가 실행 중일 때 **Tools**를 열고 **Open ADB (device port number)**를 선택합니다. 항목에 포트가 표시되며 기본값은 역시 16384입니다. MAS의 스캔에 나타나지 않으면 **Custom Port**로 추가하세요.

Mac의 MAS에는 adb 바이너리가 필요합니다. 앱 번들 안, PATH, Homebrew 폴더 순으로 찾습니다. MAS가 "ADB executable not found. Please install ADB using your package manager"를 표시하면 Homebrew로 adb를 설치하고 MAS를 다시 시작하세요:

```bash
brew install android-platform-tools
```

MAS는 항상 `127.0.0.1`로 연결하므로 MuMu Player가 같은 Mac에서 실행되어야 합니다.

## 문제 해결

### MuMu ADB 포트

MAS에 `MuMu` 항목이 없거나, 표시된 항목이 다른 인스턴스의 것입니다.

- **Issues Diagnostic** 또는 **MuMuPlayer Multi-instance 12**의 ADB 아이콘에서 포트를 읽어 기기 카드와 비교하고 **Edit Device**로 고치세요.
- 16384부터 인스턴스마다 32씩, 포트가 사용 중이었다면 1을 더해 세어 보세요(16384 대신 16385).
- 인스턴스가 아직 부팅 중이라 포트가 아직 열리지 않았습니다. 홈 화면을 기다리고 **Refresh**를 클릭하세요.
- 포트가 16576보다 크거나 스캔 규칙 밖입니다. **Custom Port**를 선택하고 입력하세요.

### MuMu ADB 연결 실패

기기 카드에 "Failed to start device"와 함께 **Error**가 표시되거나, 로그에 "unable to connect to device"가 나오거나, adb가 "cannot connect" 또는 "connection refused"를 출력합니다.

- 그 포트에서 수신하는 것이 없습니다. 위 방법으로 번호를 확인하고 인스턴스가 실행 중인지 확인하세요.
- 두 번째 adb 서버가 오래된 항목을 갖고 있습니다. 자체 adb 서버를 실행하는 다른 도구를 닫고 **Stop**을 클릭한 뒤 인스턴스를 다시 시작하고 **Start**를 클릭하세요. MAS가 처음부터 다시 연결합니다.
- `adb devices`에 포트가 `offline`으로 나옵니다. 인스턴스를 다시 시작하고, 계속 offline이면 MAS를 다시 시작해 adb 서버를 깨끗하게 시작하세요.
- 스캔이 "Failed to scan emulator ports"를 표시했습니다. MAS를 다시 시작하고 대화 상자를 다시 여세요.

adb의 원본 응답을 보려면 터미널에서 `adb connect 127.0.0.1:16384`를 실행하세요. 더 많은 해결법은 [ADB 문제 해결](/docs/adb-troubleshooting)에 있습니다.

### MuMu에서의 매크로 반복

**Infinite loop to manual stop**으로 설정된 녹화는 반복을 계속해야 하는지 판단할 수 없어 목표에 도달하거나 팝업이 떠도 계속 탭합니다. MAS 매크로는 파이썬에서 정지 조건과 함께 반복합니다: 나타나는 템플릿, OCR로 읽은 숫자, 반복 횟수. [반복, 정지 조건, 예약 실행](/docs/guides/loops-and-scheduling)에 패턴이 있습니다. MAS 반복이 멈추면 기기 카드의 **Logs**를 여세요. `ImageNotFoundError`와 `TimeoutError`가 실패한 단계를 알려 주며, 보통 원인은 템플릿과 더 이상 맞지 않는 해상도입니다.

## 파이썬으로 제어

카드가 **Running**이면 매크로의 `src/app.py`가 `mas` 패키지로 인스턴스를 조작합니다. 포트는 MAS가 고르므로 스크립트에서 참조할 일이 없습니다.

```python
import mas

size = mas.get_screen_size()
mas.log(f"MuMu screen is {size.width}x{size.height}")

match = mas.find_object_retry(1234, total_tries=3, time_sleep=2.0)
if match:
    mas.click(match.x, match.y)
```

모든 네임스페이스는 [SDK 개요](/docs/sdk)에서, 완전한 첫 스크립트는 [파이썬으로 안드로이드 에뮬레이터 제어하기](/docs/guides/control-an-emulator-from-python)에서 읽어 보세요.