FastMouseLogger 0.1.1 [ALPHA-2026-08-19] — Native Raw Mouse Logging, Stream Compression & Heatmap Engine

---

⚡ High-performance raw mouse input logger, microsecond .mousebin dual-format streaming engine, and ARGB heatmap generator for Java.

FastMouseLogger captures raw Windows mouse input directly via FastMouse (WM_INPUT bypass of OS ballistics), compresses events in real-time into binary .mousebin logs using FastFileFormat & FastBinary, and computes high-resolution behavioral heatmaps and click density distributions.

Watch Demo (YouTube) | Watch JMH Benchmark (Youtube)

---

Quick Start

import fastmouselogger.*;
import java.awt.image.BufferedImage;
import java.nio.file.Path;
import java.util.List;

public class Demo {
    public static void main(String[] args) throws Exception {
        Path logDir = Path.of("logs/mouse");

        // 1. Live background capture
        try (FastMouseLogger logger = new FastMouseLogger(logDir, 5000)) {
            logger.addListener(rec -> {
                if (rec.isButtonPress()) {
                    System.out.printf("Click at t=%d flags=0x%02X\n", rec.timestamp(), rec.flags());
                }
            });

            logger.start();
            Thread.sleep(3000);
            logger.stop(); // Flushes to timestamped .mousebin
        }

        // 2. High-speed FastFileFormat codec & heatmap rendering
        Path sessionFile = logDir.resolve("session.mousebin");
        List<MouseEventRecord> events = MousebinCodec.readFromFile(sessionFile);
        BufferedImage heatmap = HeatmapGenerator.generate(events, 1920, 1080);
    }
}

Table of Contents

• Why FastMouseLogger?
• Quick Start
• Key Features
• Real-World Scenarios
• Performance Benchmarks
• API Quick Reference
• Technical Examples & Hero Demos
• Installation
• Documentation
• Platform Support
• License
• Related Projects

---

Why FastMouseLogger?

Standard desktop interaction loggers and UI analytics tools in Java introduce severe performance degradation and data loss:

• OS Ballistics & Acceleration: Standard AWT/Swing listeners capture modified, non-linear coordinates instead of raw physical sensor movement.
• Heavy JSON/CSV Storage Overhead: Text-based logging formats inflate disk storage to gigabytes and cause massive serialization GC pauses.
• Event Dropping at High Polling Rates: Gaming and esports mice (1,000 to 8,000 Hz) flood standard queues, causing thread lockups and dropped clicks.
• Slow Offline Rendering: Reconstructing heatmaps and trajectories from raw logs usually requires external Python scripts and minutes of rendering time.

FastMouseLogger solves this fundamentally:

• True Sub-Millisecond Raw Stream: Captures raw hardware sensor deltas directly via FastMouse (WM_INPUT).
• Dense FastFileFormat Binary Storage: Serializes millions of events into ultra-compact .mousebin files with VarInt delta compression (Payload ID 0x0003).
• Zero-GC Streaming Pipeline: Pre-allocated ring buffers and bulk block writing avoid JVM heap churn.
• High-Speed In-Process Heatmaps: Renders high-density ARGB movement trajectories and click density heatmaps at over 550 Full HD frames/sec.

---

Key Features

• 🖱️ Win32 Raw Input Interception — Sub-millisecond direct mouse capture bypassing OS cursor smoothing via FastMouse.
• ⚡ FastFileFormat .mousebin Compression — Delta-timestamped VarInt event serialization (Payload ID 0x0003).
• 🔥 Hardware-Accelerated Heatmap Generation — High-speed ARGB accumulator and rasterizer for movement trajectories and click hotspots.
• 🔄 Zero GC Pressure — Contiguous memory buffers, reusable event records, and batch disk flush pipelines.
• 📦 Zero Heavy Dependencies — Native-speed pure Java 17+ core backed by FastCore, FastBinary, and FastFileFormat.

---

Real-World Scenarios

• 🤖 AI Agent Behavioral Recording — Logging human mouse interaction trajectories for imitation learning and GUI robot training.
• 🎮 Esports & Aim Analytics — Tracking raw sensor deltas, acceleration curves, and click latencies in gaming environments.
• 📊 UX & Usability Heatmaps — Visualizing user attention hotspots and click distributions on desktop applications.
• 🛡️ Biometric Telemetry — Capturing fine-grained micro-movement signatures for desktop authentication.

---

Performance Benchmarks

FastMouseLogger is profiled using JMH to guarantee maximum stream throughput and zero dropped input packets.

Benchmark Operation	Score (ops/ms)	Event Throughput	Memory Overhead
Binary Stream Decoding (.mousebin)	~75,000 ops/ms	> 75 Million events/sec	Zero-Copy Streaming
Binary Stream Encoding (.mousebin)	~50,000 ops/ms	> 50 Million events/sec	Compact VarInt Delta Buffer
Heatmap Rasterization (800x600 ARGB)	~550 ops/sec	550 Full HD Frames/sec	Direct Pixel Buffer Writing

Run the benchmarks locally: .\run-benchmark.bat

---

API Quick Reference

Method / Class	Return Type	Description	Docs
new FastMouseLogger(path, threshold)	FastMouseLogger	Creates a background raw mouse logger flushing into .mousebin.	Reference
logger.start()	void	Begins background raw mouse input interception.	Reference
logger.stop()	void	Stops capture and flushes pending memory records to disk.	Reference
logger.addListener(listener)	void	Subscribes to real-time MouseEventRecord movement and click callbacks.	Reference
MousebinCodec.encode(events)	byte[]	Serializes mouse records into compressed FastFileFormat binary byte array.	Reference
MousebinCodec.decode(bytes)	List<MouseEventRecord>	High-speed zero-copy deserialization from .mousebin binary stream.	Reference
HeatmapGenerator.generate(events, w, h)	BufferedImage	Renders high-density ARGB movement and click heatmap (>550 FPS).	Reference

---

Technical Examples & Hero Demos

Case	Java Example	Launcher	Description
Live Mouse Streamer & Heatmap Demo	Demo.java	run-demo.bat	3-second live raw recording, .mousebin encoding/decoding, and ARGB heatmap generation.
JMH Microbenchmark Suite	Benchmark.java	run-benchmark.bat	High-throughput encoding/decoding benchmarks and heatmap rasterization speed.

---

Installation

Option 1: Maven (JitPack)

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastMouseLogger</artifactId>
        <version>0.1.1</version>
    </dependency>
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastMouse</artifactId>
        <version>0.1.1</version>
    </dependency>
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastFileFormat</artifactId>
        <version>0.1.1</version>
    </dependency>
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastBinary</artifactId>
        <version>0.1.1</version>
    </dependency>
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastCore</artifactId>
        <version>0.1.0</version>
    </dependency>
</dependencies>

Option 2: Gradle (via JitPack)

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.andrestubbe:FastMouseLogger:0.1.1'
    implementation 'com.github.andrestubbe:FastMouse:0.1.1'
    implementation 'com.github.andrestubbe:FastFileFormat:0.1.1'
    implementation 'com.github.andrestubbe:FastBinary:0.1.1'
    implementation 'com.github.andrestubbe:FastCore:0.1.0'
}

Option 3: Direct Download (No Build Tool)

Download the latest JARs directly to add them to your classpath:

1. 🖱️ FastMouseLogger-0.1.1.jar (Mouse Logger & Heatmap Engine)
2. ⚡ FastMouse-0.1.1.jar (Native Win32 Raw Mouse Input)
3. 📄 FastFileFormat-0.1.1.jar (Dual Binary & Text File Format)
4. ⚡ FastBinary-0.1.1.jar (VarInt & Binary Packing)
5. ⚙️ fastcore-0.1.0.jar (Foundation Library)

---

Documentation

• REFERENCE.md: Full API reference and method signatures.
• PHILOSOPHY.md: Architectural design principles and zero-drop input goals.
• CHANGELOG.md: Release history and version notes.
• ROADMAP.md: Future milestones and planned features.
• COMPILE.md: Instructions for compiling from source.

---

Platform Support

Platform	Architecture	Status	Driver / Subsystem
Windows 10 / 11	x64	✅ Fully Supported	Native Win32 WM_INPUT (RawInput via FastMouse)
Linux	x64 / AArch64	🚧 Planned	evdev / libinput Relative Pointer Stream
macOS	Apple Silicon / x64	🚧 Planned	Quartz Event Taps (CGEventTap)

---

License

MIT License. See LICENSE file for details.

---

Related Projects

• FastMouse — Ultra-low latency raw mouse capture for Windows
• FastKeyboard — Low-level raw keyboard event interceptor
• FastKeylogger — Biometric typing cadence and keystroke logger
• FastFileFormat — Universal dual-format binary & text document engine
• FastSharedMemory — Zero-copy inter-process shared memory for Java

---

Part of the FastJava Ecosystem — Making the JVM faster. Small package. Maximum speed. Zero bloat. 🚀📋