HIDMaestro Documentation

Ship a controller in minutes. Trace it to the wire.

HIDMaestro creates virtual game controllers that look like real hardware to Windows. These docs serve two readers at once. Start and the SDK pages get an application developer to a live controller fast. The Technical Reference goes as deep as IOCTL dispatch tables and shared memory layouts, for people who want to know exactly what the driver does.

Get started Technical Reference

New here

Start

Reference the SDK, install the driver, and create your first virtual controller. No prior knowledge assumed.

The API

SDK

The public C# surface: contexts, controllers, descriptors, force feedback, output passthrough, and name overrides.

Every device

Profiles

The JSON profile system, 337 built-in devices, custom and cloned devices, and the extractor that captures yours.

Something broke

Troubleshooting

Symptoms, causes, and fixes for driver installs, missing devices, XInput slots, and output that never arrives.

Go deep

Technical Reference

Architecture, driver internals, the shared memory protocol, PnP lifecycle, and how every gaming API is satisfied.

New in v2.0.1

Removing HIDMaestro

One tool or one call takes the controllers, driver, certificate, keys and files, puts shared Windows keys back, and says what stays.

New in v2.0.0

Moving from 1.x

Devices are profile data now, and the 2.0.0 driver takes precedence over every older one. Programs built on 1.x must move to 2.0.0. Here is what changes.

New in v2.0.0

Programs side by side

Two or more programs that embed HIDMaestro on one machine, each keeping its own controllers, and a driver deploy that never downgrades.

New in v2.0.0

Wii U GameCube adapter

The four-port adapter Melee players use, for Dolphin, Slippi and SDL, described entirely by its profile.

New in v1.12

Keyboards and mice

51 keyboards and 52 mice copied from real devices, every report delivered, and nothing left held when a consumer dies.

What HIDMaestro is

A C# SDK and matching UMDF2 driver. Add the SDK to your app, call HMContext.InstallDriver() once, and HMContext.CreateController(profile) whenever you need a virtual gamepad, keyboard or mouse. It replaces ViGEmBus and vJoy with one user-mode driver, 337 embedded profiles, runtime-built custom profiles, HID PID 1.0 force feedback, and live-swap teardown that does not leak PnP state.

v2.0.1 removes HIDMaestro from a computer, with HIDMaestroUninstall.exe from the release ZIP or with HMUninstall.Run() from a program, and installs usbip-win2's host controller without its installer or root-hub filter. See Removing HIDMaestro.

v2.0.0 moves device behavior out of code and into the profiles, and its driver takes precedence over every older one. Programs built on HIDMaestro 1.x must move to 2.0.0. See Moving from 1.x.

v2.0.0 runs two or more programs that embed HIDMaestro on one machine, and between programs on v2.0.0 or later none removes or writes to another's controllers, driver or files outside the remove-everything cleanup. See Programs Side by Side. The SDK also works in NativeAOT and trimmed single-file apps, and a build can leave out the ARM64 payload or the USB/IP transport. See Build and Release. The Wii U GameCube adapter, the four-port adapter Melee players use, is a profile that Dolphin, Slippi and SDL read through libusb. See Wii U GameCube Adapter.

v1.12 adds keyboards and mice: 51 keyboards and 52 mice copied from real devices, plus starters for building your own. See Keyboards and Mice.

v1.11 added a Switch 2 Pro Controller with motion, for Steam and SDL. See Switch 2 Pro with Motion.

v1.10 added a DualShock 3 with pressure-sensitive buttons, in the form PCSX2 and RPCS3 read. See DualShock 3.

v1.9 added ARM64 Windows. The same HIDMaestro.Core.dll carries a driver set for x64 and one for ARM64 and installs the one matching the machine. Use v1.9.1 or later on ARM64. See platform support.

Who ships it

PadForge uses HIDMaestro for virtual controller output. It is built on this SDK end to end and drives more of the surface than any other consumer: every profile family, live profile swapping, multi-controller slots, force feedback, controller audio and haptics, the Valve personas, and the virtual VR controllers. Its Softpedia listing is an Editor's Pick at 5.0 out of 5. To watch the SDK work without writing any code, install PadForge.

Others include foundation-sunshine, a Sunshine fork whose DualSense support is built on HIDMaestro, Vibepollo, a Sunshine fork whose DualSense over USB/IP draws on HIDMaestro's composite descriptors, Kitsune Input, whose virtual gamepad is derived from HIDMaestro, HandHeld Legend's HHL Gamepad WLAN for HOJA gamepads, and JoystickGremlinEx, which drives the SDK from Python over pythonnet. More are listed on the specifications page.

What HIDMaestro is not

A standalone app. There is no UI to drive HIDMaestro on its own. Consumers like PadForge wrap the SDK with their own input pipeline. If you want to use HIDMaestro through a UI, install PadForge.

HIDMaestro is free and open source, MIT licensed. The code, issues, and releases live at github.com/hifihedgehog/HIDMaestro.