libvirtualhid

libvirtualhid

Cross-platform C++ virtual HID library.

Overview

ℹ️ About

libvirtualhid provides a platform-neutral C++ API for creating virtual input devices. The primary target is gamepad input for remote streaming hosts and other low-latency applications, with keyboard, mouse, touchscreen, trackpad, and pen tablet support available where the platform backend supports those device types.

Consumers work with portable concepts such as runtimes, device profiles, normalized gamepad state, output callbacks, and device nodes. Platform-specific details such as Linux uhid/uinput or the Windows UMDF/VHF driver package stay behind backend implementations.

🎮 Capabilities

• Gamepad profiles for generic HID, Xbox 360, Xbox One, Xbox Series, DualShock 4, DualSense, and Nintendo Switch Pro-style controllers.
• Descriptor-driven Linux gamepads through uhid, plus keyboard, mouse, touchscreen, trackpad, and pen tablet devices through uinput.
• Windows gamepads through a user-mode UMDF2 control driver backed by Virtual HID Framework, with keyboard and mouse support through normal Win32 APIs.
• Output callbacks for profile-specific feedback such as rumble, LEDs, adaptive triggers, and raw HID output reports when available.
• An optional virtualhid_control native UI tool for creating, removing, controlling, and inspecting test gamepads through the public C++ API.
• CMake consumption through installed packages, vendored source, add_subdirectory, or FetchContent.

🚀 Quick Start

#include <libvirtualhid/libvirtualhid.hpp>
 
auto runtime = lvh::Runtime::create();
auto created = runtime->create_gamepad(lvh::profiles::dualsense());
if (!created) {
  return;
}
 
auto &gamepad = *created.gamepad;
gamepad.set_output_callback([](const lvh::GamepadOutput &output) {
  // Forward rumble, LEDs, adaptive triggers, or raw reports to the client.
});
 
lvh::GamepadState state;
state.buttons.set(lvh::GamepadButton::a, true);
state.left_stick = {0.25F, -0.5F};
state.right_trigger = 1.0F;
 
gamepad.submit(state);

More complete examples live in examples/, including the streaming-host-oriented examples/gamepad_adapter.cpp.

📚 Documentation

• Usage and API: CMake consumption, build options, public API overview, profiles, and examples.
• Platform support: backend capability model, Windows, Linux, macOS, and Linux permission setup.
• Windows driver package: UMDF/VHF package build, installation, validation, diagnostics, and signing notes.
• Streaming-host integration: integration contract and remaining replacement-readiness work for streaming hosts.
• Development: local build/test commands, repository layout, docs generation, and roadmap.
• Microsoft Store validation: review notes and manual validation for Store submissions.

🎯 Scope

libvirtualhid owns local virtual device creation and input/output report translation. It does not provide a network protocol, parse client packets, own a consumer application's configuration system, bypass anti-cheat systems, hide devices from the OS, or ship a Windows kernel-mode driver.

📌 Status

Linux and Windows are the active backends. Linux uses standard user-space kernel interfaces. Windows remains user-mode: the C++ library talks to a UMDF2 control driver, and the driver publishes HID gamepads through VHF. macOS support is not implemented yet.

The library is designed around gamepad use first because remote streaming hosts are the first consumer class. Non-gamepad device types are available through the same API where the backend exposes them.

🔁 Alternatives

Alternatives exist if libvirtualhid does not meet your needs.

Feature	libvirtualhid	ViGEmBus	HIDMaestro	inputtino	WinUHid
Windows support	✅	✅	✅	❌	✅
Linux support	✅	❌	❌	✅	❌
Windows AMD64 support	✅	✅	✅	-	✅
Windows ARM64 support	❌5	✅	❌6	-	✅
Windows user-mode driver	✅	❌	✅	-	✅
No Windows kernel-mode driver	✅	❌	✅	-	✅
Descriptor-defined HID devices	✅	❌	✅	✅1	✅
Platform-neutral C++ API	✅	❌2	❌2	❌3	❌2
Keyboard	✅	❌	❌	✅	✅4
Mouse	✅	❌	❌	✅	✅4
Touchscreen, trackpad, or pen	✅	❌	❌	✅	✅4
Generic HID gamepad	✅	❌	✅	❌	✅4
Xbox 360 gamepad	✅	✅	✅	❌	✅4
Xbox One gamepad	✅	❌	✅	✅	✅4
Xbox Series gamepad	✅	❌	✅	❌	✅4
DualShock 4 gamepad	✅	✅	✅	❌	✅4
DualSense gamepad	✅	❌	✅	✅	✅4
Nintendo Switch Pro-style gamepad	✅	❌	✅	✅	✅4
Rumble or output callbacks	✅	❌	✅	✅	✅4
Data-driven profiles	❌	❌	✅	❌	❌
Actively developed	✅	❌	✅	✅	✅

¹ inputtino uses uhid for virtual joypads; its other listed device types use Linux input interfaces rather than generic HID descriptors.

² Windows-only project, so it does not provide a platform-neutral API surface.

³ Linux-only project, so it does not provide a platform-neutral API surface.

⁴ WinUHid is a framework-level virtual HID target; support requires a custom HID descriptor and matching report handling rather than a ready-made device profile.

⁵ libvirtualhid has architecture-aware WiX packaging, but the built Windows driver package target is AMD64 today. Windows ARM64 release driver packages require a Microsoft dashboard signing path, such as WHQL/Hardware Dev Center signing; the current Azure Trusted Signing catalog/MSI flow is not sufficient for ARM64 release driver package installation.

⁶ HIDMaestro documents a win-x64 test app path and does not currently advertise an ARM64 build.

📄 License

The cross-platform libvirtualhid library is licensed under the MIT License. The Windows UMDF driver source and generated Windows driver package artifacts, including the driver MSI, are licensed under the LizardByte Source-Available License 1.0 (LB-SAL 1.0). See the license map for the full repository split.