Skip to main content

SmartMouse 🖱️

PyPI version Python versions License: MIT

SmartMouse is a Python package that simulates realistic, human-like mouse movements using recorded movement patterns from real users. Unlike simple linear interpolation or basic curves, SmartMouse uses actual human movement data to create authentic mouse trajectories with realistic timing.

🌟 Features

  • Authentic Human Movement: Uses real recorded mouse movement data
  • Multiple Movement Patterns: Different patterns for various distances and directions
  • Realistic Timing: Includes authentic pause and movement timing
  • Easy Integration: Simple API that works with existing automation tools
  • No External Data Required: Comes with built-in movement patterns
  • Customizable: Support for custom movement data and parameters
  • Cross-Platform: Works on Windows, macOS, and Linux

📦 Installation

Install SmartMouse using pip:

pip install smart-mouse

Or install from source:

git clone https://github.com/Bandit-HaxUnit/humanmouse.git
cd humanmouse
pip install -e .

🚀 Quick Start

Basic Usage

from smart_mouse import SmartMouse

# Create a mover instance (uses built-in movement data)
mover = SmartMouse()

# Move to a specific coordinate
mover.move_to(500, 300)

# Move through multiple points
points = [(100, 100), (300, 200), (500, 400)]
mover.move_along_path(points)

Simple API

from smart_mouse import create_mover

# Even simpler way to create a mover
mover = create_mover()
mover.move_to(800, 600)

Advanced Usage

from smart_mouse import SmartMouse, generate_random_points

# Create mover with custom settings
mover = SmartMouse(
    enable_mouse_control=True,  # Set to False for testing
    distance_thresholds=[10, 20, 50, 100, 200, 500]  # Custom distance categories
)

# Generate random test points
screen_width, screen_height = 1920, 1080
random_points = generate_random_points(5, screen_width, screen_height, padding=100)

# Move through random points with custom pause timing
mover.move_along_path(random_points, pause_range=(0.5, 1.2))

# Get information about available movement patterns
print("Available distances:", mover.get_available_distances())
print("Movement data stats:", mover.get_stats())

Custom Movement Data

# Use your own movement data file
mover = SmartMouse(mouse_data_file="my_custom_movements.json")

# Or provide movement data directly
custom_data = {
    "50": {  # Distance bucket
        "N": [  # Direction (North)
            [
                [0, 1, 1, 0],      # X offsets
                [1, 1, 0, -1],     # Y offsets  
                [8.3, 4.1, 6.2, 12.1]  # Timing (milliseconds)
            ]
        ]
    }
}
mover = SmartMouse(mouse_data=custom_data)

Callbacks and Monitoring

def movement_callback(x, y, step_index):
    print(f"Step {step_index}: Moving to ({x:.1f}, {y:.1f})")

# Move with callback to monitor progress
path = mover.move_to(400, 300, callback=movement_callback)
print(f"Movement completed with {len(path)} steps")

📖 API Reference

SmartMouse

The main class for generating human-like mouse movements.

Constructor

SmartMouse(
    mouse_data_file=None,     # Optional path to movement data file
    mouse_data=None,          # Optional movement data dict
    distance_thresholds=None, # Custom distance buckets
    enable_mouse_control=True # Whether to actually move the mouse
)

Methods

  • move_to(target_x, target_y, start_x=None, start_y=None, callback=None) - Move to coordinates
  • move_along_path(points, pause_range=(0.3, 0.8), callback=None) - Move through multiple points
  • generate_path(start_x, start_y, target_x, target_y) - Generate path without moving
  • get_current_position() - Get current mouse position
  • set_position(x, y) - Set mouse position instantly
  • get_available_directions(distance) - Get available movement directions
  • get_available_distances() - Get all distance buckets
  • get_stats() - Get movement data statistics

Utility Functions

  • create_mover(**kwargs) - Convenience function to create a SmartMouse
  • generate_random_points(num_points, screen_width, screen_height, padding=100) - Generate random coordinates

Movement Data Format

The movement data uses this JSON structure:

{
  "distance_bucket": {
    "direction": [
      [
        [x_offset_1, x_offset_2, ...],     // X coordinate offsets
        [y_offset_1, y_offset_2, ...],     // Y coordinate offsets  
        [time_1, time_2, ...]              // Timing in milliseconds
      ]
    ]
  }
}

Distance buckets are strings representing maximum pixel distances (e.g., "50", "100"). Directions are: "N", "NE", "E", "SE", "S", "SW", "W", "NW".

🔧 Development

Setting Up Development Environment

git clone https://github.com/Bandit-HaxUnit/humanmouse.git
cd humanmouse
pip install -e ".[dev]"

Running Tests

pytest tests/

Code Formatting

black humanmouse/
flake8 humanmouse/

Building and Publishing

# Build the package
python -m build

# Upload to PyPI (requires credentials)
python -m twine upload dist/*

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

This package is intended for legitimate automation, testing, and accessibility purposes. Please ensure you comply with the terms of service of any applications you automate and respect user privacy and consent.

🙏 Acknowledgments

  • Thanks to all the users who contributed their mouse movement data
  • Inspired by the need for more realistic automation in testing and accessibility tools
  • Built with love for the Python automation community

Made with ❤️ by HaxUnit

Metadata

Release files for smart-mouse 1.0.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for smart-mouse 1.0.5
File Size Uploaded Provenance Actions
smart_mouse-1.0.5.tar.gz 59.5 kB Without provenance Details for smart_mouse-1.0.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for smart-mouse 1.0.5
File Interpreter ABI Platform Actions
smart_mouse-1.0.5-py3-none-any.whl Python 3 none any Details for smart_mouse-1.0.5-py3-none-any.whl

Total release size: 112.5 kB

Release files / smart_mouse-1.0.5.tar.gz

Download URL smart_mouse-1.0.5.tar.gz
Size 59.5 kB
Tags Source
SHA-256 checksum
How to use checksums
dd7dda1f718fd3cc5b9135857b3ec9548523eb19cd9f4a52b01d1a1c8500006b
BLAKE2b-256 checksum
How to use checksums
710fa7850621f7a7d43cdfd4b7ec925c2f655a55ef653dbbbc213ff7e801afc0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.11.9

Release files / smart_mouse-1.0.5-py3-none-any.whl

Download URL smart_mouse-1.0.5-py3-none-any.whl
Size 53.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1345d7a9e2ae2445aab0bdf06e42fb53206caa8ce723994a2622c4d4dcf9247b
BLAKE2b-256 checksum
How to use checksums
ba9b633f805f968815a077ce467a3d05221c83d16c58a7230d30a2089d46b659
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.11.9

Security for smart-mouse 1.0.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page