🖱️ MouseReplayer

A behavioral mouse dynamics research platform for HCI, biometrics, and motor-behavior analysis.

Overview

This laboratory environment captures and analyzes human-computer interaction signatures through high-frequency telemetry. By recording natural pointing trajectories, the framework enables the study of motor variability, intra-user consistency, and the boundary between human and synthetic interaction patterns. Applications span behavioral biometrics, accessibility research, adaptive interface design, and the development of automated-interaction detectors.

Core Features

• Kinetic Baseline Engine: Employs a 5th-order minimum-variance polynomial model to synthesize optimized point-to-point trajectory vectors for comparative analysis.
• High-Frequency Capture: Implements low-overhead Pygame event listeners capable of streaming multi-column kinematic features directly into structured Apache Parquet stores.
• Hardware Playback Engine: A non-blocking relative coordinate playback system using Linux uinput for sub-millisecond replication of captured trajectories.
• Validation Matrix: Fully-vectorized alignment pipeline built with NumPy and Pandas to benchmark synthetic trajectory accuracy against human captures.

Intended Research Applications

• Behavioral biometrics and motor-signature analysis
• Human-computer interaction studies
• Accessibility research and motor impairment analysis
• Adaptive interface design
• User experience research
• Human-in-the-loop agent design
• Synthetic interaction benchmarking
• Detection of automated interaction patterns — the same data that enables trajectory synthesis also serves to train and evaluate detectors that distinguish human from automated input.

Ethical Use

This project is intended for research, education, and experimentation in behavioral biometrics and human-computer interaction. It is not designed, documented, or supported for circumventing security systems, access controls, CAPTCHAs, rate limits, fraud detection mechanisms, or terms of service.

Quick Start

pip install -r requirements.txt

# Interactive capture session
python3 -m mousereplayer record

# Replay a recorded session (dry-run on non-Linux)
python3 -m mousereplayer playback sessions/*.parquet --dry-run

# Validate playback fidelity against a human recording
python3 -m mousereplayer validate sessions/human.parquet sessions/replay.parquet

# List and inspect recorded sessions
python3 manage.py list
python3 manage.py inspect sessions/*.parquet

Project Structure

mousereplayer/
├── arena/            # Rendering, target primitives, deterministic canvas generation
├── telemetry/        # Sampling, kinematic recording, feature extraction
├── storage/          # Parquet I/O, date-based session organization
├── analytics/        # Kinetic baseline model, validation and segment comparison
├── tracking/         # PlaybackEngine — consolidated uinput playback driver
├── observability/    # Colored console and file logging
├── config.py         # Frozen dataclass configuration
├── controller.py     # AppController — recording lifecycle coordinator
├── main.py           # CLI entry point
└── manage.py         # Session listing and inspection utility

CLI Reference

Command	Description
record	Launch interactive capture session
playback <path>	Replay a recorded trajectory
validate <human> <synth>	Compare trajectories against baseline

Controls

Input	Action
Left-click targets	Advance scenario sequence
R	Regenerate target layout
Escape / Q	Terminate session

Telemetry Schema

Samples are recorded at 120 Hz and persisted as Apache Parquet with the following columns: timestamp, x, y, dx, dy, velocity, acceleration, jitter, target_id, inside_target, mouse_button_state, event_type, distance_to_target, movement_angle, click_active, hover_duration. Motion is captured continuously during click events — no freeze or dropout windows.