⌨️ Keyboard Tester

Ultra-Lightweight Hardware Switch Telemetry & Keystroke Analyzer for Windows

A high-performance (~364 KB), portable, standalone native Windows utility engineered to test physical keyboard switches, switch chattering/bounce, peak N-Key Rollover (NKRO), hold duration, and actuation latency with microsecond precision.

---

📋 Table of Contents

• Overview
• Key Features
• Technology Architecture
• How to Use
  • Interactive Testing
  • Background Operation & System Tray
  • Live Telemetry Logging
  • Audio Actuation Feedback
  • Exporting Reports
• Safety, Privacy & Security
• Building from Source
• License

---

Overview

Keyboard Tester is designed for keyboard enthusiasts, competitive gamers, hardware reviewers, and quality assurance engineers who need precise switch telemetry without bloated Electron runtimes, third-party drivers, or network dependencies.

Built directly against the native Windows Win32 and GDI subsystems, it starts instantaneously, consumes under 15 MB of RAM, and delivers microsecond-accurate physical switch measurements.

---

✨ Key Features

1. Dynamic Hardware Layouts & Auto-Expansion

Switch seamlessly across 4 physical keyboard form factors:

• Full (104-Key): Standard desktop layout with full Number Pad and navigation block.
• TKL (87-Key): Tenkeyless layout omitting the numeric pad.
• Laptop (75%): Compact notebook layout with clustered navigation and tucked arrow keys.
• Minimal (60%): Compact alphanumeric cluster.
• Smart Auto-Expansion: Automatically switches to the Full 104-Key layout if any numeric pad key is pressed while in a compact mode.

2. True Physical Numpad & Modifier Detection

• Correctly distinguishes between Numpad Enter and Main Enter via extended scan code parsing.
• Distinguishes Left vs. Right modifiers (LShift / RShift, LCtrl / RCtrl, LAlt / RAlt).
• Accurately maps physical Numpad keys even when NumLock is turned off.

3. Microsecond Hold & Latency Measurement

• Uses Windows hardware performance counters (QueryPerformanceCounter) to measure switch press duration down to fractions of a millisecond.
• Helps identify faulty switch actuation, dirty mechanical contacts, and switch chattering/key-bounce anomalies.

4. Real-Time N-Key Rollover (NKRO) & Ghosting Monitor

• Simultaneously tracks all concurrently held keys in real time.
• Records and displays the Peak NKRO achieved during the testing session to evaluate keyboard hardware ghosting and matrix limitations.

5. Automatic Real-Time Live File Logging

• Streams every keystroke (DOWN, RPT, UP) directly into Logs/keyboard_live_log.txt.
• Immediately flushes each event to disk via FlushFileBuffers with zero write-caching latency.
• Opens the log with shared read permissions (FILE_SHARE_READ), allowing live file tailing in PowerShell or text editors while the application runs.

6. Background Operation & System Tray Minimization

• Minimize to Tray Button: Clicking [ ▽ Minimize to Tray ] or the standard window minimize button hides the window to the Windows notification tray.
• Non-Intrusive Background Hook: The low-level keyboard hook continues tracking and logging keystrokes transparently while passing all inputs untouched to your foreground games, browsers, or text editors.
• Tray Context Menu: Right-click the system tray icon to quickly restore the window, open the live log file, toggle sound, or exit.

7. Zero-Latency Audio Synthesis Engine

• Synthesizes crisp mechanical click feedback using an asynchronous 8-channel waveOut ring buffer.
• Runs purely in-memory without disk I/O or worker thread overhead.
• Default OFF: Audio is completely silenced by default until explicitly enabled.
• Focus Safety: Audio clicks are restricted to foreground interaction so your typing in other applications remains silent.

8. High-Contrast Dark Interface & Vector Scaling

• Built with a modern slate-navy dark palette with vibrant emerald green verified highlights and cyan active indicators.
• Smooth GDI double-buffered rendering guarantees zero visual tearing or flicker.
• Full Per-Monitor V2 DPI awareness ensures sharp rendering on 1080p, 1440p, and 4K displays.

---

🛠️ Technology Architecture

Component	Technology	Description
Language	C++17	Clean, modern native C++ compiled without runtime overhead
GUI Framework	Pure Win32 API / GDI	Direct Windows subsystem API calls; zero Electron/Qt dependencies
Rendering	GDI Double-Buffering	Off-screen memory DC (CreateCompatibleDC, BitBlt) for 60+ FPS flicker-free graphics
Input Interception	WH_KEYBOARD_LL Hook	Low-level global hook capturing raw hardware virtual key codes and scan codes
Precision Timers	QueryPerformanceCounter	Hardware-backed high-resolution timers for microsecond hold measurement
Audio Synthesizer	WinMM (waveOut*)	Multi-channel ring buffer generating sine/decay click waveforms in RAM
System Tray	Shell API (Shell_NotifyIconW)	Native Windows taskbar notification tray integration with balloon tooltips
Theming	DWM API (dwmapi.dll)	Immersive Windows 10/11 dark title bar support
DPI Scaling	Per-Monitor V2 (user32.dll)	Crisp vector scaling across mixed-DPI multi-monitor environments
Binary Compiler	MinGW GCC (g++ / windres)	Optimized, stripped, static native executable with embedded PE VERSIONINFO

---

📖 How to Use

Interactive Testing

1. Launch KeyboardTester.exe.
2. Press any key on your keyboard.
3. Observe key states:
   • Dark Navy (#1C2333): Untested switch.
   • Cyan Outline (#00E5FF): Currently depressed / held switch.
   • Emerald Green (#10B981): Verified / tested switch.
4. Check the live telemetry HUD for:
   • Last Key Actuated: Key label and friendly name.
   • Key Codes: Hexadecimal and decimal Virtual-Key (VK) and hardware scan codes.
   • Hold Duration: Exact physical contact closure duration in milliseconds.
   • Active Held Keys: Real-time simultaneous key count.
   • Peak NKRO: Maximum simultaneous keys registered in the session.
   • Progress Gauge: Percentage of keys verified in the current layout.

Background Operation & System Tray

• Minimizing: Click the [ ▽ Minimize to Tray ] button in the bottom toolbar or click the standard window minimize button (_).
• Notification: A system tray notification confirms the application is running in the background.
• Restoring: Left-click or double-click the tray icon to restore the main window.
• Tray Menu: Right-click the tray icon to access:
  • Open Keyboard Tester: Restores the window.
  • Open Live Log File: Opens Logs/keyboard_live_log.txt directly in your default text editor.
  • Sound: ON / OFF: Toggles actuation click audio.
  • Exit: Unhooks the keyboard listener and closes the application cleanly.

Live Telemetry Logging

All keystrokes are automatically logged to disk in real time.

• File Location: Logs/keyboard_live_log.txt
• Sample Output:

  ================================================================================
    KEYBOARD TESTER LIVE TELEMETRY LOG - SESSION STARTED: 2026-09-02 22:37:43
  ================================================================================
  [2026-09-02 22:37:44.686] DOWN A              VK: 0x41 ( 65)   Scan: 0x001E
  [2026-09-02 22:37:44.786] UP   A              VK: 0x41 ( 65)   Scan: 0x001E   Held: 100.2 ms
  --- SESSION ENDED: 2026-09-02 22:45:11 | Total Presses: 142 | Peak NKRO: 6 ---
  

• Live Monitoring via PowerShell:

  Get-Content .\Logs\keyboard_live_log.txt -Wait

Audio Actuation Feedback

• Default State: Audio clicks are turned OFF by default upon launch.
• Enabling: Click ■ Sound: OFF in the bottom bar to switch to ▶ Sound: ON, or toggle it via the tray menu.
• Safety Feature: Audio clicks will only play when Keyboard Tester is the active focused window. Background typing will never trigger unwanted sounds.

Exporting Reports

• Copy Report: Click ⎘ Copy Report to generate and copy a comprehensive diagnostic summary to the Windows clipboard.
• Export Report: Click ⤓ Export Report to generate a timestamped report file saved to Reports/keyboard_report_YYYYMMDD_HHMMSS.txt.
• Reset / Clear:
  • ↺ Reset: Clears tested key states, counters, and peak rollover statistics.
  • ✕ Clear Log: Clears the on-screen live event stream widget.

---

🔒 Safety, Privacy & Security

Important

Zero Network Activity: Keyboard Tester does not contain any networking sockets, HTTP libraries, or remote telemetry code. It operates 100% offline. No data ever leaves your computer.

Safe Background Monitoring

• When minimized to the tray or running in the background, the application uses WH_KEYBOARD_LL in a strictly passive monitoring configuration.
• It never blocks, swallows, or delays keystrokes when working in other applications (CallNextHookEx is always returned).
• Typing passwords, working in games, or using full-screen applications is completely unaffected.

Live Log Security Considerations

• Because the real-time live log (Logs/keyboard_live_log.txt) records all hardware keystroke events while active:
  • If you type sensitive information (such as credentials or private tokens) while the tool is running, those keystrokes will be stored in your local log file.
  • To maintain privacy, you can delete or clear Logs/keyboard_live_log.txt at any time, or close the application when typing sensitive credentials.
  • The log file is stored locally in the application folder and is never transmitted anywhere.

No Administrative Privileges Required

• Keyboard Tester runs entirely in standard user space. It does not require Run as Administrator or UAC elevation.

---

⚙️ Building from Source

Prerequisites

• Windows 10 or Windows 11 (x86_64).
• MinGW-w64 GCC (g++) with windres installed and added to your PATH.

Build Command

Simply execute the automated build batch file:

build.bat

What the Build Script Does

1. Compiles Resource File:

   windres resource.rc -O coff -o resource.res

   Embeds the application icon, high-DPI manifest, and version metadata.

2. Compiles & Links C++ Application:

   g++ -Os -s -static -static-libgcc -static-libstdc++ -fno-exceptions -fno-rtti -ffunction-sections -fdata-sections -mwindows -municode KeyboardTester.cpp resource.res -o KeyboardTester.exe -Wl,--gc-sections -ldwmapi -lgdi32 -lcomctl32 -lwinmm -lshell32

   • -Os: Size-optimized compilation.
   • -static: Statically links GCC runtimes so no MinGW DLLs are required.
   • -fno-exceptions -fno-rtti: Removes C++ runtime overhead for maximum performance.
   • -Wl,--gc-sections: Eliminates unused code sections.

3. Strips Binary:

   strip --strip-all KeyboardTester.exe

   Produces an ultra-compact standalone binary (~364 KB).

---

📄 License

This project is licensed under the MIT License. You are free to use, modify, distribute, and integrate this software for personal or commercial projects.