OBS Web Browser Fullscreen Scene Switcher

Synchronize an OBS scene with the state of a web browser window on Windows. The helper detects both browser-level fullscreen (F11) and HTML5 video fullscreen, then switches between two OBS scenes through OBS WebSocket.

The included userscript reports HTML5 video fullscreen changes to the helper over a loopback HTTP endpoint. This is useful when a video player enters fullscreen without the entire browser window entering F11 fullscreen.

Requirements

• Windows 10 or later
• Python 3.11 or later
• OBS Studio with WebSocket server access enabled (OBS 28+ includes OBS WebSocket 5)
• Userscript-supporting web browser and a userscript manager such as Violentmonkey or Tampermonkey

Install the Python dependencies from PowerShell:

py -m pip install keyboard obsws-python psutil pywin32

OBS setup

1. Create two scenes in OBS: one for fullscreen and one for the normal browser view.
2. In OBS, open Tools > WebSocket Server Settings and enable the WebSocket server.
3. Note the server host, port, and password. The default port is 4455.
4. Make sure the computer running this script can reach the OBS host and port.

Configuration

Copy config.example.toml to config.toml and edit the values:

Copy-Item config.example.toml config.toml

Required settings:

Setting	Description
OBS_HOST	Hostname or IP address of the computer running OBS.
OBS_PASSWORD	OBS WebSocket password, if configured.
SCENE_FULLSCREEN	OBS scene selected while browser is fullscreen.
SCENE_WINDOWED	OBS scene selected while browser is windowed.
BROWSER_WINDOW_TITLE	Title substrings used to identify the browser window.

Optional settings include OBS_PORT (default 4455), LOCAL_PORT (default 8765), POLL_SECONDS (default 0.35), DEBUG, BROWSER_CMDLINE_HINTS, and BROWSER_WINDOW_PROFILE_HINTS. See config.example.toml for details.

Do not commit real OBS passwords or other private network settings. Keep local credentials in config.toml and use the example file as the shareable template.

Running

From the project directory, run:

py .\obs-browser-screen-sync.py

To target a specific web browser process, pass its process ID. This skips title and profile matching and includes windows owned by the process and its child processes:

py .\obs-browser-screen-sync.py --browser-pid 12345

To use another configuration file:

py .\obs-browser-screen-sync.py --config .\config.toml

Press Ctrl+C to stop the helper.

Userscript installation

1. Install a userscript manager in your web browser.
2. Create a new userscript.
3. Copy the contents of userscript-fullscreen-ping.js into it and save.
4. Start obs-browser-screen-sync.py before using HTML5 video fullscreen.

The script sends only fullscreen state and a per-page identifier to http://127.0.0.1:8765/ by default. If LOCAL_PORT is changed, update the url constant in the userscript to match.

How it works

• The Python process polls matching browser windows for F11-style fullscreen.
• The userscript reports HTML5 video fullscreen state to the local listener.
• Either state causes the configured fullscreen scene to be selected; when neither is active, the windowed scene is selected.
• When a configured scene is selected manually in OBS, the helper attempts to put the browser window into the corresponding fullscreen state.

With no --browser-pid, the helper uses the configured title, command-line, and profile hints to find the correct window. If multiple web browser instances are running, PID targeting is the most reliable option.

Troubleshooting

• OBS connection fails: verify the WebSocket server is enabled, the host and port are reachable, and the password matches.
• No browser window is found: enable DEBUG = true, review the printed window information, or use --browser-pid.
• HTML5 fullscreen is not detected: make sure the userscript is enabled for the page and that the local listener port matches the userscript URL.
• Scene switching does not happen: check that both configured scene names exactly match scenes in OBS.

License

This project is licensed under the MIT License. See LICENSE.