SmartMouse 🖱️
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 coordinatesmove_along_path(points, pause_range=(0.3, 0.8), callback=None)- Move through multiple pointsgenerate_path(start_x, start_y, target_x, target_y)- Generate path without movingget_current_position()- Get current mouse positionset_position(x, y)- Set mouse position instantlyget_available_directions(distance)- Get available movement directionsget_available_distances()- Get all distance bucketsget_stats()- Get movement data statistics
Utility Functions
create_mover(**kwargs)- Convenience function to create a SmartMousegenerate_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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.