How to add a controller overlay to OBS

What you need

Three things: OBS Studio, a controller connected to the same computer, and an overlay link.

OBS calls its Browser source “quite literally, a web browser that you can add directly to OBS”, and lists it as available on Windows, macOS and Linux. That is all a controller overlay needs. The overlay is a web page that draws a controller and lights up each button as you press it. OBS loads the page as a layer over your game.

The page reads the controller from inside the browser source. So the controller has to be plugged into, or paired with, the computer that runs OBS. A pad that is connected only to a console cannot be read by the page.

Get your overlay link

1. Open the studio and pick the pad you hold: the PS5 DualSense, the PS4 DualShock 4 or the Xbox controller.
2. Pick a skin. The stock look of each pad is free. The other skins are in the vault.
3. Sign in with a free account, save, and copy your overlay link. It has the form controlleroverlay.com/v/ followed by a token.

Saving and copying the link both need the account. The link itself works without signing in, which is what lets OBS load it, so treat it like a password and keep it off screen.

Add the Browser source

These steps are from the OBS Sources Guide and the Browser Source page of the OBS knowledge base.

1. In OBS, select the scene you stream your game from.
2. Click the + button at the bottom of the Sources dock. The Add Sources list opens.
3. Choose Browser from the list.
4. In the source’s properties, leave Local file off and paste your overlay link into the URL field, replacing the address OBS puts there by default.
5. Leave Width at 800 and Height at 600. These are the OBS defaults, and the size the overlay is laid out for.
6. Leave Custom CSS alone. The CSS that OBS fills in sets the page background to transparent, removes the margins and hides the scroll bar, which is what an overlay wants.
7. Confirm the properties, then press any button on your controller. You should see the pad in the preview, and the button you pressed should light up.

Sources

Audio Output Capture

Browser

Color Source

Display Capture

Game Capture

Properties for “ControllerOverlay”

URL

controlleroverlay.com/v/ovl_k7Qm2x

Width

800

Height

600

Place and size it

The overlay arrives as an 800 × 600 box with nothing in it but the controller. Select it in the Sources list and OBS draws a red bounding box around it in the preview.

1. Drag the box to a corner your game’s HUD leaves free.
2. Drag one of the red handles on a corner to make the pad smaller.
3. To cut empty space off an edge, hold Alt (Option on a Mac) and drag a handle. OBS turns that edge green while it crops.
4. For exact numbers, select the source and open Edit → Transform → Edit Transform, or press Ctrl-E (Cmd-E on a Mac).

Keep 800 × 600 in the properties and do the shrinking in the scene. The properties set the size of the page; the handles set how large it is on stream.

Order matters too. OBS draws a source that is higher in the Sources list on top of the ones below it. If you added the Browser source and cannot see the pad, drag it above your game capture in the list.

Browser source settings worth knowing

The same properties window has a few switches. OBS documents them like this:

• Shutdown source when not visible unloads the page when the source is hidden with the eye icon or is not in the active scene. It is off by default. With it on, the overlay page starts fresh every time the source comes back, and you may need to press a button again before the pad reacts.
• Refresh browser source when scene becomes active reloads the page each time you switch to its scene. Also off by default, with the same effect on the first press.
• Refresh cache of current page is a button. It reloads the page at once. Use it when the overlay looks stuck.
• Use custom frame rate is off by default, and the FPS field under it defaults to 30.

For a controller overlay the defaults are the right choice: the page stays loaded between scenes.

If the pad does not react

Work down this list.

1. Press a button. A browser does not show a controller to a web page until a button has been pressed. The W3C Gamepad specification puts it this way: the list of gamepads is empty “before a gamepad user gesture has been seen”.
2. Check where the controller is connected. It has to be on the computer that runs OBS, over USB or Bluetooth.
3. Look for a message in the source. “This OBS overlay link does not exist” means the link is incomplete or wrong, so copy it again from the studio. “Stream link active on another device” means the same link is open somewhere else. One link runs in one place at a time. Close the other copy, or click Refresh cache of current page in the properties to take the link back.
4. Wrong buttons light up. Sony pads paired over Bluetooth often report their buttons to the browser in a non-standard order. The overlay corrects the common orders automatically. If yours is still mixed up, the calibrator in the studio remaps it in 10 presses, and it is part of the free account.

One more case has a source outside this site. The OBS project has an open report, issue 14083, titled “Controller inputs not being read in browser source after OBS loses focus”, filed against OBS 33.0.0 on macOS. Gamepad Viewer’s status page describes the same thing from OBS 33.0.0 on and suggests running OBS as administrator on Windows, or going back to OBS 32.2.2. We have not tested ControllerOverlay on OBS 33, so we cannot tell you whether you will see it. If your pad stops moving the moment you click into your game, those two workarounds are the ones published so far.

Change the look later

You set the source up once. The link is permanent, and the page inside OBS checks in about every 12 seconds. When you save a different skin, colour or name in the studio, the overlay on stream follows without a new link and without a refresh.

A free account covers the stock PS5, PS4 and Xbox looks, the link and the Bluetooth fix. The vault is $9.99, paid once, and adds every other skin plus button, light and name options; the pricing page has the full list. Each pad has its own page with what it shows on stream: the PS5 controller overlay, the PS4 controller overlay and the Xbox controller overlay.

Streaming from another app? The same link goes into Streamlabs Desktop as a Browser Source and into TikTok LIVE Studio as a Link source.

Gamepad Viewer in OBS

If you came here looking for how to get Gamepad Viewer into OBS, the OBS half is the same. Its own instructions are to build a link in its URL Generator, create a browser source in OBS and paste the link into the URL box, then work the width and height “up or down from the default values”.

What differs is on the overlay’s side. A Gamepad Viewer link carries the skin and settings as parameters, and colour changes go through a CSS file. A ControllerOverlay link stays the same while you change the design on the site. The Gamepad Viewer alternative page compares the two line by line, including what Gamepad Viewer does that ControllerOverlay does not.