libvirtualhid

Cross-platform C++ virtual HID library.

🎮 Windows Virtual HID Driver License

A license is required to create virtual gamepads, keyboards, or Raw Input-visible mice with the Windows driver.
This requirement is Windows-only; non-Windows backends do not currently require a license.
Yearly and lifetime options are available.

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.

• Gamepad profiles for generic HID, Xbox 360, Xbox One, Xbox Series, DualShock 4, DualSense, and Nintendo Switch Pro-style controllers.
• Descriptor-driven PlayStation, Switch Pro, Xbox One, and Xbox Series gamepads through Linux uhid; Generic and Xbox 360 gamepads plus keyboard, mouse, touchscreen, trackpad, and pen tablet devices through uinput. Xbox One and Xbox Series fall back to uinput when uhid is unavailable.
• Windows gamepads, keyboards, and Raw Input-visible mice through a user-mode UMDF2 control driver backed by Virtual HID Framework, with Win32 keyboard and mouse fallbacks when the licensed driver path is unavailable.
• Output callbacks for profile-specific feedback such as ordinary and trigger rumble, RGB and player 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 and mice through the public C++ API.
• CMake consumption through installed packages, vendored source, add_subdirectory, or FetchContent.

#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.

• End-user gamepad guide: Sunshine and Moonlight setup, feature caveats, troubleshooting, and controller support references.
• 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.
• Development: local build/test commands, repository layout, docs generation, and roadmap.
• TODO: known larger compatibility gaps and proposed solution paths.

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.

Linux and Windows provide virtual-device 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, keyboards, and mice through VHF. macOS currently provides a limited CoreGraphics synthetic-input backend for keyboard and mouse only. It is not a virtual-HID backend and does not yet support gamepads; native macOS virtual-HID gamepad support is planned.

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.

• The published Windows driver installer is AMD64-only. Windows ARM64 release packages require a different Microsoft driver-signing path.

Alternatives exist if libvirtualhid does not meet your needs.

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

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

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

4 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.

5 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.

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

The cross-platform libvirtualhid library is licensed under the MIT License. The Windows UMDF driver, broker, proprietary entitlement/evaluation sources, and generated Windows driver package artifacts, including the driver MSI, are licensed under the LizardByte Source-Available License 1.0 (LB-SAL 1.0). The root license notice points to both complete license texts; see the license map for the authoritative repository path and artifact assignments.