OBS HUD Overlay — Install Guide

A transparent, always-on-top status bar that shows recording/streaming status, FPS, timer, disk space, and bitrate directly on your screen.

Prerequisites

• Windows 10/11
• OBS Studio (any recent version)
• Python 3.9+ — download here
• Microsoft PowerToys (for always-on-top) — download here
• Obs Overlay Py File (Main File) download here

Step 1: Install Python Packages

Open Command Prompt or PowerShell and run:

text

pip install pygame obsws-python

That's it — just two packages.

Step 2: Enable OBS WebSocket

1. Open OBS Studio
2. Go to Tools → WebSocket Server Settings
3. Make sure "Enable WebSocket Server" is checked
4. Note the Port (default is 4455)
5. If you set a password, you'll need to edit the script — see Advanced: Custom Port/Password below

Step 3: Run the HUD

1. Place obs_hud_overlay.py anywhere you want (e.g., your Desktop)
2. Double-click it, or open a terminal in the same folder and run:text
3. 
   
4. python obs_hud_overlay.py
5. You should see a semi-transparent bar appear at the top-left of your screen
6. A green dot on the right side of the bar means it's connected to OBS

Step 4: Make It Always-on-Top (PowerToys)

Since the HUD is transparent, Windows can't pin it on top by itself. Use PowerToys:

1. Make sure PowerToys is installed and running
2. Click on the OBS HUD overlay bar to focus it
3. Press Win + Ctrl + T — the bar is now pinned on top of everything
4. Done. It will stay on top of games, browsers, folders, etc.

Controls

Key

Action

F11Open/close the settings panelF12Quit the HUD

Settings Panel (F11)

Press F11 to open a dark-themed settings window with:

• Toggle HUD elements — checkboxes for FPS, Timer, Disk Space, Bitrate, Dropped Frames
• Bitrate: stream only — hides bitrate when you're only recording (not streaming)
• HUD Position slider — slide left/right to position the bar across all your monitors in real time
• Background Opacity slider — 0% (fully invisible) to 100% (solid dark bar)

All settings auto-save to hud_settings.json next to the script.

Advanced: Custom OBS Port / Password

Open obs_hud_overlay.py in any text editor (Notepad works) and find these lines near the top:

python

OBS_HOST = "localhost"

OBS_PORT = 4455

OBS_PASSWORD = ""

Change OBS_PORT and OBS_PASSWORD to match your OBS WebSocket settings.

Troubleshooting

Overlay is all black / solid:

→ The script failed to apply transparency. Make sure you're on Windows and running the latest version of the script.

No green connection dot:

→ OBS WebSocket is either not enabled or on a different port. Check Step 2.

HUD disappears behind other windows:

→ Re-apply PowerToys always-on-top: click the bar and press Win + Ctrl + T.

F11 settings doesn't open:

→ Don't hold F11 — just press it once. If it still doesn't work, restart the script.

"Missing Python packages" error:

→ Run pip install pygame obsws-python again and make sure Python is added to your PATH during installation.

How It Works

• Connects to OBS locally via WebSocket (no internet needed)
• Renders a transparent overlay using pygame + Windows UpdateLayeredWindow API
• Runs in the background at ~4 FPS to minimize CPU usage
• Settings are saved to a JSON file so they persist between sessions