PymordialBlue

Advanced Android Automation for BlueStacks

PymordialBlue is a powerful extension of the Pymordial framework, specialized for automating Android applications on the BlueStacks emulator. It provides a robust, high-performance interface for controlling apps, interacting with UI elements, and performing OCR-based text extraction.

🚀 Features

• BlueStacks Integration: Native control of the BlueStacks player process (start, stop, load detection).
• High-Performance Streaming: Uses screenrecord and PyAV for low-latency (<100ms) screen capture, far faster than traditional ADB screencap.
• Smart UI Detection: Find elements by:
  • Image: Template matching with scale and confidence awareness.
  • Pixel: Fast color checks at specific coordinates.
  • Text: Tesseract OCR integration for reading dynamic text.
• Robust Lifecycle Management: State machines for Apps (CLOSED -> LOADING -> READY) and Emulator (CLOSED -> LOADING -> READY).
• Resilient ADB: Auto-reconnection, key event injection, and shell command execution.
• Typed Configuration: Full type hinting and validation for all config options.

🛠️ Installation

PymordialBlue is managed with uv.

# Clone the repository
git clone https://github.com/IAmNo1Special/PymordialBlue.git
cd PymordialBlue

# Sync dependencies (including local Pymordial)
uv sync

⚡ Quick Start

Here is a minimal example to connect to BlueStacks and capture the screen:

from pymordialblue import PymordialBluestacksController

# Initialize controller (auto-detects BlueStacks and ADB)
controller = PymordialBluestacksController()

# Connect and verify state
if controller.is_bluestacks_ready():
    print("BlueStacks is ready!")
    
    # Capture a frame
    frame = controller.capture_screen()
    print(f"Captured frame shape: {frame.shape}")
    
    # Go home
    controller.go_home()

📚 Documentation

Full documentation is available in the docs/ directory or via the MkDocs site.

• User Guide
• Core Concepts
• UI Interaction
• Configuration
• Examples

📂 Project Structure

• src/pymordialblue: Core package source.
  • devices/: Device implementations (ADB, UI, BlueStacks).
  • utils/: Configuration and helper strategies.
• examples/: Runnable scripts demonstrating key features.
• docs/: Markdown documentation.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.