pymordialblue 0.1.1
PymordialBlue: Advanced Android Automation for BlueStacks using Pymordial
Requires Python: >=3.13

# PymordialBlue

**Advanced Android Automation for BlueStacks**

PymordialBlue is a powerful extension of the [Pymordial](https://github.com/IAmNo1Special/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`.

```bash
# 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:

```python
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](https://iamno1special.github.io/PymordialBlue).

*   [User Guide](https://github.com/IAmNo1Special/PymordialBlue/blob/main/docs/user_guide/index.md)
*   [Core Concepts](https://github.com/IAmNo1Special/PymordialBlue/blob/main/docs/user_guide/core_concepts.md)
*   [UI Interaction](https://github.com/IAmNo1Special/PymordialBlue/blob/main/docs/user_guide/devices/ui.md)
*   [Configuration](https://github.com/IAmNo1Special/PymordialBlue/blob/main/docs/user_guide/configuration.md)
*   [Examples](https://github.com/IAmNo1Special/PymordialBlue/blob/main/examples/README.md)

---

## 📂 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.