📱 MirrorPy

One-click Android screen mirroring & control — powered by scrcpy

---

MirrorPy is a lightweight desktop GUI for scrcpy that makes mirroring your Android phone to your PC effortless. It features automatic device discovery via ADB mDNS, QR code pairing, and a one-click Quick Mirror button — no command line needed.

✨ Features

Feature	Description
🔍 Smart Auto-Detect	Discovers Android devices via ADB mDNS — no manual IP entry needed
⚡ Quick Mirror	One button: detect → connect → mirror in seconds
📷 QR Code	Live QR code encodes adb connect string for easy sharing
🎨 Modern UI	Clean ttkbootstrap interface with dark/light themes
📱 Device Card	Shows phone model, IP, and connection status at a glance
🌐 Network Scan	Ping sweep to find devices on your subnet
🔗 USB & Wi-Fi	Supports both USB debugging and wireless ADB over Wi-Fi
🛡️ Thread-Safe	All background operations are marshalled to the UI thread
📋 ADB Devices	Dropdown list with one-click device selection
💾 Persistent Config	Settings saved automatically between sessions

🚀 Quick Start

Prerequisites

• Windows 10/11 (tested), Linux/macOS (experimental)
• Python 3.8+ (download)
• Android device with Developer Options enabled
• ADB & scrcpy binaries (included in this repo)

Install

git clone https://github.com/Rfannn/mirrorpy.git
cd mirrorpy
pip install -r requirements.txt

Run

python mirror.py

Or double-click mirror.bat if using the embedded Python distribution.

📖 Usage

One-Click Mirror (Recommended)

1. Enable Developer Options on your Android phone
2. Enable USB Debugging or Wireless Debugging
3. Click ⚡ Quick Mirror — that's it!

MirrorPy will automatically:

• Discover your device via ADB mDNS
• Connect to it
• Launch scrcpy for screen mirroring

Manual Connection

1. Click 🔍 Detect Device to find your phone
2. Or enter the IP:port manually
3. Click 🔌 Connect, then ▶ Mirror

Pairing (Wireless Debugging)

If your phone requires pairing (Android 11+):

1. Go to Settings → Developer Options → Wireless Debugging → Pair device
2. Enter the Pair Port and Pairing Code in MirrorPy
3. Click 🤝 Pair

🏗️ Architecture

mirrorpy/
├── mirror.py              # Main application (GUI + logic)
├── test_mirror.py         # Unit tests (38 tests)
├── requirements.txt       # Python dependencies
├── settings.ini           # User configuration (gitignored)
├── .gitignore
├── adb.exe                # ADB binary (included)
├── scrcpy.exe             # scrcpy binary (included)
├── python/                # Embedded Python (optional)
└── .github/
    └── workflows/
        ├── ci.yml         # CI: lint + test
        └── release.yml    # Release automation

Key Components

Component	Purpose
full_discover()	Combined ADB devices + mDNS discovery
adb_mdns_discover()	Discover devices via adb mdns services
generate_qr_pil()	Generate QR codes for connection strings
ScrcpyLauncher	Main GUI application class
DeviceCard	Widget showing detected device info
GuiLogger	Thread-safe scrolling log widget

🧪 Testing

# Run all tests
python -m unittest test_mirror -v

# Run specific test class
python -m unittest test_mirror.TestFullDiscover -v

Tests cover:

• Helper functions (get_local_ip, ping_host, run_cmd)
• ADB device parsing and mDNS discovery
• QR code generation
• Auto-detect returns phone IP (not laptop IP)
• Config save/load
• Thread safety

🔄 CI/CD

MirrorPy uses GitHub Actions for continuous integration and automated releases:

CI Pipeline

• Linting: flake8 for code quality
• Security: bandit for vulnerability scanning
• Testing: Unit tests on Windows and Linux
• Python versions: 3.9, 3.10, 3.11, 3.12

Releases

• Trigger: Push a tag (e.g., v2.1.0)
• Builds: Windows .exe and Linux .AppImage
• Release notes: Auto-generated from commits
• Artifacts: Uploaded to GitHub Releases

Creating a Release

# Tag the release
git tag v2.1.0

# Push the tag to trigger the release workflow
git push origin v2.1.0

The release workflow will:

1. Build executables for Windows and Linux
2. Create a GitHub Release with auto-generated notes
3. Upload the executables as release assets

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/Rfannn/mirrorpy.git
cd mirrorpy
pip install -r requirements.txt
python -m unittest test_mirror -v

Code Style

• Python 3.8+
• Follow existing conventions
• Add tests for new features
• Keep commits atomic and well-described

📋 Changelog

See CHANGELOG.md for a detailed history of changes.

v2.0.0 (Latest)

• ⚡ Quick Mirror — one-click detect → connect → mirror
• 🔍 Smart Auto-Detect — uses ADB mDNS to find real Android devices
• 📷 QR Code — live QR code for connection strings
• 🎨 Redesigned UI — device card, connection wizard, status indicators
• 🛡️ Thread Safety — all tkinter updates marshalled to main thread
• 🧪 38 unit tests — comprehensive test coverage

v1.0.0

• Initial release
• Basic scrcpy launcher with USB/Wi-Fi support
• ttkbootstrap GUI
• Network subnet scan

🛠️ Troubleshooting

Problem	Solution
Python not found	Install Python 3.8+ and add to PATH
No module named ttkbootstrap	Run pip install ttkbootstrap
scrcpy not found	Ensure scrcpy.exe is in the project folder or on PATH
ADB device not found	Enable USB/Wireless Debugging; same Wi-Fi network
Auto-detect finds nothing	Check ADB server: run adb start-server manually
QR code not updating	Re-detect the device to refresh IP/port

📄 License

This project is licensed under the Apache License 2.0 — see LICENSE for details.

🙏 Acknowledgments

• scrcpy by Genymobile — the mirroring engine
• ttkbootstrap — modern tkinter themes
• qrcode — QR code generation

---

Made with ❤️ by Rfannn