Mumu Control

MuMu Emulator Control

Control MuMu Player 12 (Netease) Android emulator on Windows using mumu-cli.exe CLI and Python automation scripts (uiautomator2 + RapidOCR).

⚠️ Windows only.

Two layers:

Note: mumu-cli.exe is the new CLI name (replaces the legacy MuMuManager.exe). If mumu-cli.exe is not found in nx_main\, fall back to MuMuManager.exe — they are functionally identical.

---

Before You Start

1. Find MuMu Installation Path

MuMuInstallPath = root directory (e.g., D:\Program Files\Netease\MuMu Player 12).

Detection chain (try in order, stop on first success):

1. Cached path — read mumu_install_path.txt in skill directory, validate <path>\nx_main\mumu-cli.exe (or MuMuManager.exe) exists 2. Registry — reg query "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\MuMuPlayer" /v UninstallString → strip \uninstall.exe 3. Default paths — probe C:\Program Files\Netease\MuMu Player 12, D:\Program Files\..., C:\Program Files (x86)\... 4. Ask user — prompt for path manually 5. Install — offer to download from https://mumu.163.com/

On success, save to cache:

echo <MuMuInstallPath> > "mumu_install_path.txt"

Key Paths

Always use the bundled `adb.exe` from nx_main\ to avoid version conflicts.

cd /d "<MuMuInstallPath>\nx_main"

2. Install Python Dependencies

pip install -r requirements.txt

3. Initialize uiautomator2

First-time setup — installs atx-agent onto the device:

python -m uiautomator2 init

Only needed once per device. Re-run after device reset.

---

mumu-cli Reference

mumu-cli.exe (aka MuMuManager.exe) is the command-line interface for managing MuMu Player 12 instances. All instance operations — launch, shutdown, app management, settings — go through this binary.

📖 Official documentation: https://mumu.163.com/redirect/nx/function/mumucli/

Binary location: <MuMuInstallPath>\nx_main\mumu-cli.exe

General syntax:

mumu-cli.exe <command> [--vmindex <N>] [subcommand]

`--vmindex` targeting rules:

Short form: -v is alias for --vmindex, e.g. -v 0 = --vmindex 0

Complete Command Table

---

Top 10 Most Common Commands

1. info — Query Emulator Status

Check instance readiness before every operation. Returns JSON with port, state, and boot status.

:: Query single instance
mumu-cli.exe info --vmindex 0

:: Query all instances
mumu-cli.exe info --vmindex all

Key output fields:

✅ Ready condition: player_state == "start_finished" AND is_android_started == true

>

⚠️ Fields marked Running only are absent when the instance is stopped. Always check is_android_started before reading adb_port.

---

2. control launch — Launch Emulator

:: Launch single instance
mumu-cli.exe control --vmindex 0 launch

:: Launch multiple instances
mumu-cli.exe control --vmindex 0,1,2 launch

:: Launch all instances
mumu-cli.exe control --vmindex all launch

After launch, poll info until is_android_started: true before sending any ADB/UI commands.

---

3. control shutdown — Shutdown Emulator

:: Shutdown single instance
mumu-cli.exe control --vmindex 0 shutdown

:: Shutdown multiple instances
mumu-cli.exe control --vmindex 0,1,2 shutdown

:: Shutdown all instances
mumu-cli.exe control --vmindex all shutdown

---

4. control restart — Restart Emulator

Use when instance is frozen, crashed, or behaving unexpectedly.

:: Restart single instance
mumu-cli.exe control --vmindex 0 restart

:: Restart multiple instances
mumu-cli.exe control --vmindex 0,1,2 restart

:: Restart all instances
mumu-cli.exe control --vmindex all restart

---

5. control hide_window / show_window — Background Mode

Run automation silently without a visible window to save screen space and resources.

:: Hide window (switch to background)
mumu-cli.exe control --vmindex 0 hide_window

:: Show window again
mumu-cli.exe control --vmindex 0 show_window

:: Batch hide all instances
mumu-cli.exe control --vmindex all hide_window

---

6. control app launch — Launch App

:: Launch app in single instance
mumu-cli.exe control --vmindex 0 app launch --package com.example.game

:: Launch in multiple instances
mumu-cli.exe control --vmindex 0,1,2 app launch --package com.example.game

:: Launch in all instances
mumu-cli.exe control --vmindex all app launch --package com.example.game

---

7. control app install — Install APK

Supports .apk, .xapk, .apks formats. Batch install to multiple instances in one command.

:: Install to single instance
mumu-cli.exe control --vmindex 0 app install --apk "C:\path\to\app.apk"

:: Install to multiple instances
mumu-cli.exe control --vmindex 0,1,2 app install --apk "C:\path\to\app.apk"

:: Install to all instances
mumu-cli.exe control --vmindex all app install --apk "C:\path\to\app.apk"

---

8. control app close — Close App

Force-stop a running app (equivalent to am force-stop).

:: Close app in single instance
mumu-cli.exe control --vmindex 0 app close --package com.example.game

:: Close in multiple instances
mumu-cli.exe control --vmindex 0,1,2 app close --package com.example.game

:: Close in all instances
mumu-cli.exe control --vmindex all app close --package com.example.game

Related app subcommands:

:: Query app state: returns running / stopped / not_installed
mumu-cli.exe control --vmindex 0 app info --package com.example.game

:: List active app (returns {"active": "<package>"})
mumu-cli.exe control --vmindex 0 app info --installed

:: Uninstall app
mumu-cli.exe control --vmindex 0 app uninstall --package com.example.game

---

9. create / clone — Create or Clone Instance

:: Create new instance (auto index)
mumu-cli.exe create

:: Create at specific index
mumu-cli.exe create --vmindex 2

:: Clone an existing instance
mumu-cli.exe clone --vmindex 0

:: Rename an instance
mumu-cli.exe rename --vmindex 0 --name "Bot-1"

:: Delete an instance
mumu-cli.exe delete --vmindex 1

---

10. setting — Configure Emulator

Get or set emulator properties (resolution, rendering mode, etc.).

⚠️ Settings can only be written when the instance is STOPPED. Writing while running returns key not writable. Always shutdown first, then modify settings, then launch again.

:: List all settings for an instance
mumu-cli.exe setting --vmindex 0 --all

:: Get individual settings (resolution is three separate keys)
mumu-cli.exe setting --vmindex 0 --key resolution_width    :: returns e.g. "1600.000000"
mumu-cli.exe setting --vmindex 0 --key resolution_height
mumu-cli.exe setting --vmindex 0 --key resolution_dpi

:: Set resolution — shutdown instance first, then set each key
mumu-cli.exe control --vmindex 0 shutdown
mumu-cli.exe setting --vmindex 0 --key resolution_width --value 1080
mumu-cli.exe setting --vmindex 0 --key resolution_height --value 1920
mumu-cli.exe setting --vmindex 0 --key resolution_dpi --value 480
mumu-cli.exe control --vmindex 0 launch

:: Apply same setting to multiple instances
mumu-cli.exe setting --vmindex 0,1,2 --key resolution_width --value 1080
mumu-cli.exe setting --vmindex 0,1,2 --key resolution_height --value 1920
mumu-cli.exe setting --vmindex 0,1,2 --key resolution_dpi --value 480

Common resolution presets (from `--all` output):

---

Other Useful CLI Commands

:: Device simulation — change device fingerprint
mumu-cli.exe simulation --vmindex 0 --simu_key android_id --simu_value <new_id>
mumu-cli.exe simulation --vmindex 0 --simu_key android_id --simu_value __null__  # reset

:: Export / Import instance backup
mumu-cli.exe export --vmindex 0 --dir "C:\backups"
mumu-cli.exe import --vmindex 1 --path "C:\backups\backup.mumudata"

:: Toolbar functions (trigger via CLI)
mumu-cli.exe control --vmindex 0 tool func --name screenshot   # take screenshot
mumu-cli.exe control --vmindex 0 tool func --name rotate       # rotate screen
mumu-cli.exe control --vmindex 0 tool func --name go_home      # press Home
mumu-cli.exe control --vmindex 0 tool func --name go_back      # press Back
mumu-cli.exe control --vmindex 0 tool func --name top_most     # pin window on top
mumu-cli.exe control --vmindex 0 tool func --name fullscreen   # fullscreen toggle
mumu-cli.exe control --vmindex 0 tool func --name shake        # shake gesture
mumu-cli.exe control --vmindex 0 tool func --name volume_up    # volume up
mumu-cli.exe control --vmindex 0 tool func --name volume_down  # volume down
mumu-cli.exe control --vmindex 0 tool func --name volume_mute  # mute toggle

:: Set window position and size
mumu-cli.exe control --vmindex 0 layout_window --pos_x 100 --pos_y 100 --size_w 1280 --size_h 720

:: Limit CPU usage (1–100%)
mumu-cli.exe control --vmindex 0 tool downcpu --cap 50

---

ADB Connection

From info JSON: serial = <adb_host_ip>:<adb_port> (e.g., 127.0.0.1:16384).

.\adb.exe connect 127.0.0.1:16384
.\adb.exe devices
:: Expected: 127.0.0.1:16384    device

:: Troubleshoot: reset ADB
.\adb.exe kill-server && .\adb.exe start-server && .\adb.exe connect 127.0.0.1:16384

---

UI Automation — Python Scripts

All scripts are in scripts/. Default serial: 127.0.0.1:16384 (override with -s <serial>).

Default output: ./tmp/mumu-control/.

Examples below omit -s for brevity — add it when using non-default serial.

Recommended Automation Loop

1. uiscan.py  → Screenshot + UI recognition → Annotated image
2. AI reads UI recognition → Annotated image → Find target via visual understanding and element annotations
3. tap.py     → Tap target (by coords or text match)
4. uiscan.py  → Verify result
5. Wait → Repeat

Simplest path (recommended): python scripts/tap.py --text "Collect" — auto screenshot → OCR → tap

⚠️ NEVER tap without a prior screenshot/scan.

---

uiscan.py — Screenshot + UI Element Recognition

Dual-source recognition: accessibility tree (dump_hierarchy) + RapidOCR. Results merged (hierarchy priority).

Output: {name}.png (annotated) + {name}_elements.json (structured data)

:: Full scan (hierarchy + OCR)
python scripts/uiscan.py

:: Custom output
python scripts/uiscan.py -o ./output -n game_state

:: Partial modes
python scripts/uiscan.py --screenshot-only
python scripts/uiscan.py --no-ocr          # hierarchy only (fast)
python scripts/uiscan.py --no-hierarchy     # OCR only (game engines)

Output JSON example:

[
  {
    "index": 0, "name": "Collect Reward", "control_type": "Button",
    "coords": {"x": 540, "y": 960}, "size": {"width": 200, "height": 60},
    "resource_id": "com.game:id/collect_btn", "clickable": true
  },
  {
    "index": 1, "name": "Daily Check-in", "control_type": "OCRText",
    "coords": {"x": 300, "y": 400}, "size": {"width": 120, "height": 30}
  }
]

---

tap.py — Tap

:: By coordinates
python scripts/tap.py 540 960

:: By text (auto screenshot → OCR → find → tap) — RECOMMENDED for games
python scripts/tap.py --text "Collect"

:: Long press
python scripts/tap.py 540 960 --long --duration 3.0
python scripts/tap.py --text "Enhance" --long

---

swipe.py — Swipe / Scroll

:: By coordinates: x1 y1 x2 y2
python scripts/swipe.py 540 1400 540 400

:: By direction (auto-calculates based on screen size)
python scripts/swipe.py --direction up|down|left|right

:: Custom speed
python scripts/swipe.py --direction up --duration 1.0

---

keyevent.py — Hardware Key Events

python scripts/keyevent.py home|back|enter|power|escape|tab|space|delete|recent
python scripts/keyevent.py volume_up|volume_down|volume_mute
python scripts/keyevent.py dpad_up|dpad_down|dpad_left|dpad_right
python scripts/keyevent.py 26    # by numeric keycode

---

input_text.py — Text Input (Supports Chinese/Unicode)

Default: clears existing text before input. Use --append to append.

:: Method 1: Resource ID (most reliable — recommended)
python scripts/input_text.py "Onmyoji" --res-id com.mumu.store:id/search_bar
python scripts/input_text.py "extra" --res-id com.mumu.store:id/search_bar --append

:: Method 2: Coordinates (when no resource ID available)
python scripts/input_text.py "hello" --coord 500 800
python scripts/input_text.py "more" --coord 500 800 --append

:: Method 3: Legacy (requires field already focused)
python scripts/input_text.py "hello world"

Finding Resource ID: Run uiscan.py, look for resource_id in output JSON or table.

---

screenshot.py — Simple Screenshot

python scripts/screenshot.py
python scripts/screenshot.py -o ./captures/screen1.png

For screenshots + element recognition, use uiscan.py instead.

---

App Management via ADB

For fine-grained single-instance control, use ADB directly:

:: Install APK
.\adb.exe -s 127.0.0.1:16384 install app.apk

:: List installed 3rd-party packages
.\adb.exe -s 127.0.0.1:16384 shell pm list packages -3

:: Force stop app
.\adb.exe -s 127.0.0.1:16384 shell am force-stop com.example.app

:: Uninstall app
.\adb.exe -s 127.0.0.1:16384 uninstall com.example.app

💡 Prefer mumu-cli.exe control --vmindex N app ... for batch multi-instance operations. Use ADB for fine-grained control on a single instance.

---

Quick Reference

---

Verify Setup

Run in order with your <serial> (default 127.0.0.1:16384):

---

Troubleshooting