Skip to content

Add opt-in outbound client mode for obs-websocket#1325

Draft
rowdytomato wants to merge 1 commit intoobsproject:masterfrom
rowdytomato:feature/obs-websocket-client-mode
Draft

Add opt-in outbound client mode for obs-websocket#1325
rowdytomato wants to merge 1 commit intoobsproject:masterfrom
rowdytomato:feature/obs-websocket-client-mode

Conversation

@rowdytomato
Copy link

@rowdytomato rowdytomato commented Feb 7, 2026

Description

Implements opt-in outbound websocket client mode while preserving existing protocol semantics:

  • OBS sends Hello
  • Controller sends Identify
  • Request/event flow remains unchanged

Client mode is opt-in and default-off.

This PR adds:

  • Shared protocol handling used by both server/client transports
  • Outbound client transport with reconnect/backoff and heartbeat behavior
  • Settings/config updates for outbound URL, auth, TLS, and explicit unsafe toggles
  • TLS build toggle support for client mode
  • Documentation and locale/string updates

Motivation and Context

Today, obs-websocket is primarily used with inbound connections to OBS.
Some deployments cannot expose inbound ports (NAT/firewall/restricted environments).
Outbound client mode enables those users to connect safely to a remote controller while keeping the existing protocol model and compatibility expectations.

How Has This Been Tested?

Validation covered inbound-server regression and outbound-client mode on Linux and Windows with TLS enabled and disabled.

  • Inbound server-mode regression:
    • External client connects to OBS websocket server
    • Performs identify/auth flow
    • Executes core request path (GetVersion)
  • Outbound client-mode:
    • OBS connects to external websocket endpoint
    • Completes Hello -> Identify -> Identified handshake
    • Verifies normal message flow and reconnect behavior
  • TLS coverage:
    • TLS enabled and disabled builds/runs
    • Runtime behavior validated for secure and explicitly-unsafe toggles
  • Manual settings checks:
    • Enable/disable client mode
    • URL/auth field validation
    • Status transitions and failure handling

Tested OS(s):

  • Ubuntu 24.04.3 LTS (WSL2 + dockerized OBS build/runtime path)
  • Windows 11 Version 25H2 (x64, native build/runtime validation)

Known Follow-up (Not in This PR)

Official release packaging for TLS-enabled client-mode artifacts may still require a companion obs-studio change (submodule bump and relevant preset/CI enablement).

Types of changes

  • Code cleanup (non-breaking change which makes code smaller or more readable)
  • Documentation change (a change to documentation pages)
  • Other Enhancement (anything not applicable to what is listed)

Checklist:

  • I have read the Contributing Guidelines.
  • All commit messages are properly formatted and commits squashed where appropriate.
  • My code is not on master or a release/* branch.
  • The code has been tested.
  • I have included updates to all appropriate documentation.

Implements opt-in outbound websocket client mode while preserving the
existing protocol semantics. OBS sends Hello, controllers Identify,
and the normal request/event flow remains unchanged.

Includes shared protocol refactor, settings/config UX updates, TLS
build toggle support, reconnect/backoff/heartbeat handling, and
documentation/string updates for client mode.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant