Gamepad API or WebHID: what a browser can read from a controller

How it works

Input sources

PadBench reads each pad through a source: the browser's Gamepad API to start with, WebHID once you allow a pad, the Windows app's engine, or the keyboard. The source decides what can be measured, and every figure says what its source could count.

The browser's Gamepad API

Every browser has the Gamepad API, and PadBench reads every pad through it until you choose otherwise. The browser reads the pad itself, and the page asks it for the pad's state once a frame, 60 times a second on most screens, and never more often than the browser reads the pad: every 4 ms at best in Chrome and Firefox, and 120 times a second in Safari.

So a press shorter than a frame can be missed, and the pad's own reports can't be counted: there is no polling rate or chatter count, and no motion, touch or battery, which the Gamepad API doesn't pass on. A browser shows a pad only once it has been used on the page, and some buttons, such as a DualSense's Mute, it never reports.

WebHID

WebHID, in Chrome and Edge on a computer, reads a pad report by report. It counts the true polling rate, sees every press however short, so chatter is counted, and reads what the Gamepad API leaves out: the buttons it doesn't report, and on a DualSense, a DualShock 4 and a Switch Pro Controller, their motion sensors and battery, and the Sony pads' touchpads. It also sets a DualSense's or a DualShock 4's lights, and a DualSense's trigger effects.

A browser opens a pad through WebHID only once you allow it. Choose WebHID among the pad's tools, where it sits beside Gamepad API, or Use WebHID where a tile offers it, then pick the pad in the browser's list. The browser remembers it for this site, and Forget in WebHID, in the pad's Controller tab, undoes it. A pad the browser doesn't list at all can be added with the + after the controller tabs.

Pads PadBench has no decoder for are read through their own descriptor, their controls numbered until PadBench knows which is which. On Windows, an Xbox pad is within WebHID's reach through the device Windows makes for a pad on its Xbox driver: its polling rate and every press, but no rumble.

The Windows app's engine

The Windows app reads pads through its own engine, which keeps reading while a game has focus, so you can test with the game running. It reads PlayStation, Switch and other HID pads report by report, up to 8,000 a second, their motion, touchpad and battery included, with no prompt to allow them; and Xbox pads through XInput, change by change, with their guide button and battery.

The keyboard

The keyboard source reads a keyboard as a controller, for a leverless board or a hitbox in keyboard mode, or for playing on a keyboard. Its keys stand for controls, by default as GP2040-CE's keyboard mode maps them, so such a board works untouched: the arrows for the d-pad, Left Shift, Z, Left Control and Left Alt for the face buttons, and so on. The keyboard's Controller tab changes any of them.

Every key press and release arrives, so none is missed; a keyboard sends only when a key changes, though, so it has no polling rate to count.

In a browser, only the mapped keys are read, and only while the keyboard's test area has focus, and browsers keep a few shortcuts, such as closing the tab, for themselves. The Windows app's keyboard capture reads the mapped keys even while a game has focus.

Keyboard mode's switch, Use a keyboard as a controller, at the end of the controller tabs, shows only with the debugging details.

Touch, motion and battery

A pad's touchpad, motion sensors and battery reach PadBench only through a source that reads them. For each, the source says one of three things: it reads it; the pad sends it only once switched to its full report, as a Sony pad on Bluetooth does; or it isn't read through this source, as through the browser's Gamepad API, which passes none of them on.

WebHID and the Windows app read all three on a DualSense and a DualShock 4, and the motion and battery of a Switch Pro Controller; the app reads an Xbox pad's battery too. Where a tile can't show one, it says why, and offers Use WebHID where that would read it.

The debugging details

Press A, B, X and Y, then Y, B and A, on a pad within four seconds, by where they sit rather than by what they say: bottom, right, left, top, top, right, bottom. The Debug tab then shows what the source reported of the pad: its id and mapping, its buttons and axes as they come, the model it is recognised as, whether every press arrives or readings are taken, and what the polling rate counts. Beside each control, its place in the pad's report shows too. The same presses hide them again.

For a pad read both ways, Compare there draws its other reading beside the one chosen: the controls only one source reports, each one's stick resolution, and how much later the Gamepad API saw each press than WebHID did. Copy details copies all of it, for a report.