# LD플레이어 ADB 연결과 디버깅 설정: MAS에 LDPlayer 추가

> LDPlayer 9에서 ADB 디버깅을 켜고 ADB 포트를 찾아 Macro Automation Studio에 연결하며, 조작 녹화기 대신 화면을 인식하는 매크로로 바꾸는 방법을 안내합니다.

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

이 가이드는 LD플레이어 ADB 연결 방법, 즉 LDPlayer 9를 Macro Automation Studio(MAS)에 ADB로 연결하는 과정과, MAS 매크로가 LDPlayer의 Operation Recorder와 어떻게 다른지 설명합니다. LD플레이어 ADB 연결은 Windows 전용입니다. LDPlayer가 Windows용으로만 제공되기 때문입니다.

## 시작하기 전에

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

## 1. LDPlayer 9 설치

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

## 2. 고정 해상도 설정

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

1. LDPlayer 도구 모음의 톱니바퀴 아이콘을 클릭해 **Settings**를 엽니다.
2. **Display**를 열고 사용자 지정 해상도 옵션을 고릅니다.
3. 너비 540, 높이 960, DPI 240을 입력합니다. 이것이 MAS 기준선입니다. 직접 쓴 매크로는 Asset Lab에서 캡처한 해상도를 기대합니다.
4. **Save settings**를 클릭하고 LDPlayer가 요청하면 인스턴스를 다시 시작합니다.

> [!WARNING]
> 템플릿을 캡처한 뒤 해상도를 바꾸면 모든 매칭 위치가 어긋나고, 다른 해상도용으로 만든 매크로는 엉뚱한 곳을 클릭합니다.

## 3. LDPlayer 9에서 ADB 디버깅 켜기

LDPlayer는 직접 열기 전까지 ADB를 닫아 둡니다. 공식 문서에 따르면 스위치는 Other settings에 있습니다:

1. **Settings**를 엽니다.
2. **Other settings**를 클릭합니다.
3. **ADB debugging**을 **Open local connection**으로 설정합니다.
4. **Save settings**를 클릭합니다.
5. 인스턴스를 다시 시작합니다. 설정은 재시작 후에 적용됩니다.

> [!NOTE]
> MAS는 항상 같은 컴퓨터에서 연결하므로 **Open local connection**이면 충분합니다. 루트 권한은 같은 페이지의 별도 옵션이며 MAS에는 필요 없습니다.

## 4. LD플레이어 ADB 포트와 MAS의 스캔 방식

첫 LDPlayer 인스턴스는 **5555**에서 수신합니다. MAS는 에뮬레이터를 찾기 위해 `adb devices`를 쓰지 않습니다. 실행 중인 프로세스를 스캔해 다음 조건이 모두 맞는 포트만 남깁니다:

- 프로세스 이름에 `ldvboxheadless`, `ld9boxheadless`, `dnplayer`, `ldplayer` 또는 `vboxnetnat`이 들어 있습니다.
- 포트가 5555에서 5599 사이의 홀수입니다: 5555, 5557, 5559 등.
- 소켓이 `127.0.0.1`, `0.0.0.0` 또는 모든 인터페이스에서 수신합니다.

조건에 맞는 포트는 **Add New Device** 대화 상자에 `LD Player` 레이블로 나타납니다. 예를 들어 `5555 - LD Player`입니다. MAS는 기기 그룹을 열 때와 **Refresh**를 클릭할 때마다 스캔합니다. 추가 인스턴스는 다음 홀수 포트를 차지하며, 규칙이 5599까지인 이유가 이것입니다. 실행 중인 인스턴스 23개까지 다룹니다.

## 5. MAS에서 LD플레이어 ADB 연결

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

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

## LDPlayer의 매크로

LDPlayer의 **Operation Recorder**(도구 모음 버튼 또는 <kbd>Ctrl</kbd> + <kbd>8</kbd>)는 탭, 스와이프, 텍스트 입력을 녹화해 스크립트로 재생합니다. 스크립트 설정에는 **Execution loop**(**Till loops number**, **Till time**, **Till manual stop**), **Loop Interval**, **Accelerating**이 있습니다. 하지만 화면을 볼 수는 없습니다. 모든 탭이 녹화한 좌표에서 재생되므로, 로딩 지연, 팝업, 위치가 바뀐 버튼이 있으면 다음 탭은 허공에 떨어지고 반복은 그대로 계속됩니다. 스크립트는 LDPlayer 안에서만 실행됩니다.

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

- 녹화한 루틴을 화면 인식 매크로로 다시 만들려면 [이미지 인식 매크로](/docs/guides/image-recognition-macros)를 따라 하세요.
- 녹화기로는 표현할 수 없는 정지 조건까지 반복하거나 예약 실행하려면 [반복, 정지 조건, 예약 실행](/docs/guides/loops-and-scheduling)을 읽어 보세요.
- Marketplace 매크로는 MAS 매크로로 설치되어 지정한 기기에서 실행됩니다.

> [!NOTE]
> MAS에서 기기를 시작하기 전에 Operation Recorder 스크립트를 멈추세요. 둘 다 같은 화면에 입력을 보내 서로 방해합니다.

## 여러 LDPlayer 인스턴스

**LDMultiplayer**(**Multi-player** 도구 모음 버튼, 그다음 **New player** 또는 **Clone player**)에서 만든 인스턴스는 각각 자기 포트로 수신합니다. 같은 기기 그룹에 각각 별도 기기로 추가하고, 기기별로 매크로와 설정 프로필을 지정한 뒤, 그룹의 **Start All**과 **Stop All**을 사용하세요. 템플릿이 모든 인스턴스에서 맞도록 관리자의 **Settings**에서 인스턴스별 해상도를 설정하세요. 기기별 인수와 프록시는 [기기 그룹](/docs/device-groups)을 참고하세요.

## 문제 해결

### LD플레이어 ADB 기기를 찾을 수 없음

기기 카드에 "Failed to start device"와 함께 **Error**가 표시되거나, 로그에 "unable to connect to device"가 나오거나, MAS에 `LD Player` 항목이 없습니다. 다음 원인을 차례로 확인하세요:

- **ADB debugging**이 **Open local connection**으로 설정되지 않았거나, 변경 후 인스턴스를 다시 시작하지 않았습니다. 설정하고 저장한 뒤 다시 시작하세요.
- 인스턴스가 아직 부팅 중입니다. 홈 화면을 기다린 뒤 **Refresh**와 **Start**를 다시 클릭하세요.
- 포트가 다른 인스턴스의 것입니다. 카드의 **Edit Device**로 고치세요.
- 스캔이 "Failed to scan emulator ports"를 표시했습니다. MAS를 다시 시작하고 대화 상자를 다시 여세요.
- 기기 로그에 adb가 "connection refused" 또는 "cannot connect"를 출력했습니다. 그 포트에서 수신하는 것이 없습니다. 터미널에서 `adb connect 127.0.0.1:5555`로 확인하세요.

### LDPlayer가 offline으로 표시됨

`adb devices`에 `127.0.0.1:<port>  offline`이 나오고 명령이 멈춥니다. 인스턴스 안의 adb 데몬이 응답을 멈춘 것으로, 보통 절전, 업데이트, 또는 같은 컴퓨터의 두 번째 adb 서버 뒤에 일어납니다. 카드에서 **Stop**을 클릭하고, LDPlayer 인스턴스를 다시 시작하고, 자체 adb 서버를 실행하는 다른 도구를 닫은 뒤 **Start**를 클릭하세요. MAS는 시작할 때마다 오래된 항목을 끊고 다시 연결합니다. 계속 offline이면 MAS를 다시 시작해 adb 서버를 깨끗하게 시작하세요. 더 많은 해결법은 [ADB 문제 해결](/docs/adb-troubleshooting)에 있습니다.

### LDPlayer 9 ADB 포트 찾기

공식 ADB 안내에는 LDPlayer 설정에서 포트가 표시되는 위치가 없으므로 MAS나 adb에서 읽으세요. MAS에서 **Add New Device**를 열고 **Refresh**를 클릭하면 찾은 모든 포트가 `LD Player`와 함께 낮은 순으로 나열되므로 첫 인스턴스는 5555, 다음은 5557, 5559 순입니다. 터미널에서 `adb connect 127.0.0.1:5555`는 살아 있는 포트에 "connected", 죽은 포트에 "cannot connect"로 응답합니다. 포트를 알고 나면 인스턴스를 같은 순서로 시작하는 한 그대로 유지됩니다.

### 매크로가 동작하지 않음

이 표현에는 두 가지 다른 문제가 섞여 있습니다.

- 녹화한 LDPlayer 스크립트가 엉뚱한 곳을 탭하거나 효과 없이 반복됩니다. 녹화 이후 해상도가 바뀌었거나, 앱 로딩이 느려졌거나, 팝업이 버튼을 덮고 있습니다. 녹화 스크립트는 이 중 어느 것도 복구할 수 없습니다. [이미지 인식 매크로](/docs/guides/image-recognition-macros)로 루틴을 MAS 매크로로 다시 만드세요.
- MAS 매크로가 멈추거나 정지합니다. 기기 카드의 **Logs**를 여세요. `ImageNotFoundError`와 `TimeoutError`가 실패한 단계를 알려 줍니다. 인스턴스가 템플릿을 캡처한 해상도로 실행 중인지, 기기 카드가 **Running**인지, 동시에 입력을 보내는 LDPlayer 스크립트가 없는지 확인하세요.

## 파이썬으로 제어

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

```python
import mas

size = mas.get_screen_size()
mas.log(f"LDPlayer 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)에서 읽어 보세요.