FastKeyboard 0.1.0 [ALPHA-2026-06-14] — Native Windows RawInput API for Java

⚡ High-performance, background-capable raw keyboard interception for Java.

---

Table of Contents

• Key Features
• Performance
• Installation
• Quick Start
• API Reference
• Platform Support
• License
• Related Projects

---

Quick Start

FastKeyboard keyboard = FastKeyboard.open();

keyboard.startListening((handle, vKey, scanCode, pressed, isExtended) -> {
    System.out.printf("Key %s: ScanCode 0x%X on Device %d\n",
        pressed ? "DOWN" : "UP", scanCode, handle);
});

---

Why Raw Input?

Standard Java APIs (AWT KeyListener or WM_KEYDOWN) are often too slow or limited for advanced telemetry. FastKeyboard solves this by intercepting events at the hardware level:

• Hardware Scancodes: Get the physical "Make Code" regardless of the OS keyboard layout (QWERTZ/QWERTY).
• Multi-Keyboard Logic: Distinguish between multiple physical devices (e.g., separate a barcode scanner from a main keyboard).
• Anti-Ghosting: Direct real-time capture of the hardware stream.

---

Key Features

• ⚡ Native Performance — Direct Win32 RawInput access via JNI.
• 🎯 Zero Overhead — No polling, purely event-driven callbacks.
• 🔑 Hardware Scancodes — Get immutable "Make Codes" instead of layout-dependent virtual keys.
• 🖥️ Multi-Device Support — Identify which physical keyboard sent the input (HID handle tracking).
• 🌑 Background Capture — Intercept keys even when your Java app is minimized or hidden.
• 🚀 Zero GC Pressure — High-performance event dispatching with minimal memory allocation.

---

Performance

FastKeyboard is designed for scenarios where every microsecond counts (e.g., behavioral language analysis, gaming):

Metric	FastKeyboard	Standard AWT Listener	Improvement
Input Latency	< 1ms	~16ms	16× Faster
Background Support	Yes	No	Full Access
Hardware ID	Yes	No	Multi-Device
Zero-Copy Signal	Yes	No	Kernel-Direct

---

Installation

Option 1: Maven (Recommended)

Add the JitPack repository and the dependencies to your pom.xml:

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

<dependencies>
    <!-- FastKeyboard Library -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastKeyboard</artifactId>
        <version>0.1.0</version>
    </dependency>

    <!-- FastCore (Required Native Loader) -->
    <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:FastKeyboard:0.1.0'
    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. 📦 fastkeyboard-0.1.0.jar (The Core Library)
2. ⚙️ fastcore-0.1.0.jar (The Mandatory Native Loader)

Important

All JARs must be in your classpath for the JNI calls to function correctly.

---

API Reference

Method	Description
static FastKeyboard open()	Factory method to create a new implementation instance.
void startListening(FastKeyboardListener listener)	Begins background raw input capture.
void stopListening()	Stops the background listener thread.
List<KeyboardDevice> getConnectedDevices()	Lists all attached HID keyboard devices.

---

Documentation

• COMPILE.md: Full compilation guide (MSVC C++17 build chain + JNI Setup).
• REFERENCE.md: Full API descriptions, border configurations, and codepoint index.
• PHILOSOPHY.md: The engineering rationale for zero-allocation performance.
• ROADMAP.md: Future milestones and planned features.

---

Platform Support

Platform	Status
Windows 10/11	✅ Fully Supported
Linux	🚧 Planned
macOS	🚧 Planned

---

License

MIT License — See LICENSE file for details.

---

Related Projects

• FastCore — Native Library Loader & JNI Utilities for Java
• FastMouse — High-Performance Native Mouse API for Java
• FastHotkey — Low-Latency Global Hotkey API for Java
• FastKeylogger — Behavioral Typing Logic for Java
• FastTouch — Native Touchscreen Input for Java
• FastStylus — Native Stylus/Pen Input for Java

---

Part of the FastJava Ecosystem — Making the JVM faster. ⚡