Connection & Reconnection

This guide covers connecting to a running OBS instance, the connection state machine, automatic reconnection, and the connection-related events you can bind to.

Enabling the OBS WebSocket Server

Before the plugin can connect, enable the WebSocket server inside OBS:

1. Open OBS Studio
2. Go to Tools → WebSocket Server Settings
3. Check Enable WebSocket server
4. Set a password (recommended)
5. Note the port (default: 4455)

Connecting

You can connect through the OBS Component (per-actor) or the OBS Subsystem (global). Both accept a host, port, and password.

Via the OBS Component (recommended for most users)

1. Add the OBS Controller component to any Actor.
2. In the Features picker at the top of the Details panel, turn on the domains you want (it starts with Scenes + Recording & Streaming, and Connection is always on).
3. In the Connection card, enter your connection settings and click Connect.
4. Use the built-in controls or bind to events in Blueprints.

The Details panel provides full control over OBS without writing any code, and shows only the features you picked, so a minimal component stays uncluttered.

Via the OBS Subsystem (Blueprint)

// Get the OBS Subsystem
Get Game Instance → Get Subsystem (InhyeongOBSSubsystem)

// Connect to OBS
Connect (Host: "localhost", Port: 4455, Password: "your_password")

// React to events
Bind to On Connected
Bind to On Disconnected

Via the OBS Subsystem (C++)

// Get subsystem
UInhyeongOBSSubsystem* OBS = GetGameInstance()->GetSubsystem<UInhyeongOBSSubsystem>();

// Connect
OBS->Connect("localhost", 4455, "password");

// Bind to events (dynamic delegates for UFUNCTIONs)
OBS->OnConnected.AddDynamic(this, &AMyActor::HandleConnected);

// Or use native delegates with lambdas
OBS->GetClient()->OnConnectedNative.AddLambda([]() {
    UE_LOG(LogTemp, Log, TEXT("Connected to OBS"));
});

Authentication

OBS uses a SHA256 challenge/response handshake when a password is set. This is handled automatically during the connection sequence, so you only need to supply the password. If a password is required but none is provided, the connection fails fast rather than hanging.

Connection State Machine

A connection moves through the following states:

Disconnected → Connecting → Authenticating → Connected

Once Connected, the client correlates requests by ID and dispatches incoming OBS events to the appropriate handlers.

Auto-Reconnect

Auto-reconnect is enabled by default. If the connection drops, the client retries using exponential backoff so it does not hammer OBS. Backoff grows per attempt, and reconnection stops once the configured maximum number of attempts is exhausted (an unlimited setting retries indefinitely).

A manual Connect() issued during an in-flight reconnect does not cancel the pending attempt. It overwrites it with the new connection target.

Connection & Reconnection Events

Bind to these to react to connection lifecycle changes.

Connection

Reconnection

Every event is available as both a Blueprint-assignable dynamic delegate and a native C++ delegate (the native variant is suffixed Native).

For the full catalog of events across every OBS domain, see the Events reference.