---

BrogsCursor gives you high-fidelity recording and replay of every mouse movement, click, and keystroke. Perfect for UI automation, testing, and creating flawless demonstrations.

from brogscursor import record

recorder = record()
recorder.start_recording()  # Press Esc to stop recording
recorder.replay(recorder.stop_recording())

Table of Contents

• Installation
• Get Started
• Features
• Creating Your First Recording
• Using the Command-Line Interface
• Customizing Settings
• Supported Platforms
• Examples
  • Minimal Example
  • Quick Record Example
  • Custom Settings Example
  • Save to File Example
  • Multiple Recordings Example
• Available Methods
• Documentation
• License

Installation

Install the latest stable version from PyPI:

pip install brogscursor

When using this package in your application, it's recommended to pin to at least the major version:

pip install brogscursor==0.1.*

Get Started

Record and replay user actions in just 4 lines of code:

from brogscursor import record

recorder = record()
recorder.start_recording()  # Press Esc to stop recording
recorder.replay(recorder.stop_recording())

Features

Feature	Description
Precise Recording	Capture mouse movements, clicks, scrolls, and keyboard events with high precision
Exact Timing	Replay actions with the same timing as the original recording
Customizable	Adjust playback speed, loop count, and more
Control	Pause/resume recording, stop replay with a hotkey
Resolution Aware	Automatically scales recorded actions to the current screen resolution
Rich CLI	Beautiful terminal interface with the Rich library
Multi-format Export	Save recordings as JSON, CSV, or human-readable text
Robust API	Comprehensive Python API for integration into your projects

Creating Your First Recording

from brogscursor import record
from brogscursor.recorder import BrogsCursorRecorder

def main():
    # Create a recorder instance
    recorder = record()
    
    print("Starting recording - press Esc to stop")
    
    # Start recording (this will block until Escape is pressed)
    recorder.start_recording()
    
    # Save the recording
    recording_file = recorder.stop_recording()
    print(f"Recording saved to: {recording_file}")
    
    # Replay the recording
    print("Replaying recorded actions...")
    recorder.replay(recording_file)

if __name__ == "__main__":
    main()

Using the Command-Line Interface

BrogsCursor provides an interactive CLI for easy recording and playback:

# Launch the interactive CLI
brogscursor

Keyboard Controls

• Esc: Stop recording
• p: Pause/resume recording
• Ctrl+C: Exit CLI

CLI Features

• Start recording with optional timeout
• List and manage saved recordings
• Replay recordings with various settings
• Customize configuration

Customizing Settings

from brogscursor import record

# Create a recorder with custom settings
recorder = record(
    log_dir="my_recordings",   # Custom directory to save recordings
    max_events=10000,          # Maximum number of events to record
    record_keyboard=True,      # Record keyboard events
    speed_multiplier=1.5       # Default replay speed
)

# Start recording with a 30-second timeout
recorder.start_recording(timeout=30)

Supported Platforms

BrogsCursor works across multiple platforms:

• Windows: Full support for mouse and keyboard recording/replay
• macOS: Full support (requires Accessibility permissions)
• Linux: Full support on X11 systems

Examples

Minimal Example

import brogscursor

# One-liner recording and replay
brogscursor.record().start_recording().replay(brogscursor.record().stop_recording())

Quick Record Example

from brogscursor import record

# Create recorder
recorder = record()

# Start recording
recorder.start_recording()

# Stop and save recording
recording_file = recorder.stop_recording()

# Replay saved recording
recorder.replay(recording_file)

Custom Settings Example

from brogscursor import record

# Custom recorder configuration
recorder = record(
    log_dir="./custom_recordings",
    max_events=20000,
    record_keyboard=True,
    speed_multiplier=1.5
)

# Start recording with 15-second timeout
recorder.start_recording(timeout=15)

# Replay with custom options
recorder.replay(
    recorder.stop_recording(),
    precision_mode=True,
    loop_count=2
)

Save to File Example

from brogscursor import record
from brogscursor.utils import export_recording
import os

# Record actions
recorder = record()
recorder.start_recording()
recording_path = recorder.stop_recording()

# Export to different formats
exports_dir = "exports"
if not os.path.exists(exports_dir):
    os.makedirs(exports_dir)

# Export as CSV
csv_path = export_recording(recording_path, "csv", os.path.join(exports_dir, "actions.csv"))
print(f"Exported to CSV: {csv_path}")

# Export as human-readable text
txt_path = export_recording(recording_path, "txt", os.path.join(exports_dir, "actions.txt"))
print(f"Exported to text: {txt_path}")

Multiple Recordings Example

from brogscursor import record
from brogscursor.utils import merge_recordings

# Create recorder
recorder = record()

# Record first sequence
print("Recording first sequence - press Esc when done")
recorder.start_recording()
first_recording = recorder.stop_recording()

# Record second sequence
print("Recording second sequence - press Esc when done")
recorder.start_recording()
second_recording = recorder.stop_recording()

# Merge recordings
merged_recording = merge_recordings([first_recording, second_recording], "merged_actions.json")
print(f"Merged recording saved to: {merged_recording}")

# Play merged recording
recorder.replay(merged_recording)

Available Methods

from brogscursor import record
from brogscursor.utils import get_recording_info, export_recording, merge_recordings

# Core recorder methods
recorder = record()
recorder.start_recording(timeout=None)  # Start recording with optional timeout
recorder.stop_recording()               # Stop and save recording
recorder.pause_recording()              # Pause current recording
recorder.resume_recording()             # Resume paused recording
recorder.list_recordings()              # List all saved recordings
recorder.replay(                        # Replay a recording with options
    "recording.json",
    precision_mode=True,
    filter_events=None,
    loop_count=1,
    stop_key='p'
)

# Utility functions
info = get_recording_info("recording.json")  # Get recording metadata
export_recording("recording.json", "csv")    # Export to different format
merge_recordings(["rec1.json", "rec2.json"]) # Combine multiple recordings

Documentation

For complete documentation, see the following resources:

• Examples: The examples/ directory contains fully-commented example scripts.
• API Documentation: See the API Reference section above.
• Command-Line Help: Run brogscursor --help for CLI documentation.
• Source Code: The source code includes detailed docstrings.

License

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