Websockets

Websockets

It is possible to use the macros system to communicate with remote OBS instances using version 5.0 of the obs-websockets plugin.
Since version 28 of OBS the obs-websocket plugin is shipped with OBS itself so there is no need to install anything for this functionality.

To receive messages the macro condition "Websocket" can be used.
To send messages to other OBS instances the macro action "Websocket" can be used.

Message types

The supported message types that can be used with the "Websocket" action and condition are "Requests" and "Events".

• Requests (1) are sent to one specific target via the specified connection.
• Events (2) are sent to all clients that are connected to the obs-websocket server the event is emitted from.

Websocket condition

This condition type will allow you to perform actions if certain messages or patterns are received from other OBS instances.

Simply enter the desired message into the text field (1).
If applicable check (2) to interpret the message as pattern to match incoming messages against.

If a matching message was received the condition will return true for the interval the message was received in.

Websocket action

This action type will allow you to send messages to other OBS instances which could then trigger macros on the remote OBS instance.

First select the connection you want to send the message to (1).
For more details on how to configure connections have a look at the upcoming sections. Next enter the message you want to send in the text field at (2).

Connections

Adding new connections

A new connection can be added to a websocket request action or websocket event condition by clicking on the "Add new connection" entry in the connection selection menu.

When selecting this entry a dialog will open in which you will have to enter the connection details:

• Unique name for this new connection (1).
• The address to connection to (2).
• The port to connect to on the specified address (3).
• The password required to connect to the websocket server (4).
• If you would like the plugin to automatically attempt to connect on OBS startup check (5).
• If you want the plugin to automatically attempt to reconnect once the connection is lost check (6) and enter the desired time after which reconnecting should be attempted.
• Finally you can check if the entered connection details are valid by clicking on the "Test connection" button (7).
  If the status message reports "Connected and authenticated" all is well.

Modifying existing connections

To modify the connection details of an existing connection simply select it in the drop down menu of a websocket action and click the marked gear symbol.
Next click the "Properties" entry and a dialog like described above will open in which you can modify the connection's settings.

The gear icon will also allow you to rename or remove existing connections.

Sending messages to the scene switcher from external tools via websocket requests

The scene switcher is using the obs-websocket protocol to send and receive messages.
This can also be used by external tools to send messages, which can be processed by the plugin and thus trigger macros.

To send a message with the contents testing one has to create a CallVendorRequest type message using a vendorName of AdvancedSceneSwitcher and a requestType of AdvancedSceneSwitcherMessage and add the "message" field with the desired contents to the requestData.

{
    "d": {
        "requestData": {
            "requestData": {
                "message": "testing"
            },
            "requestType": "AdvancedSceneSwitcherMessage",
            "vendorName": "AdvancedSceneSwitcher"
        },
        "requestId": "someUniqueIdHere",
        "requestType": "CallVendorRequest"
    },
    "op": 6
}

Example "Bitfocus Companion"

Below is an example configuration that can be used to send message Requests from "Bitfocus Companion" to the Advanced Scene Switcher plugin.

Field	Value
Request Type	CallVendorRequest
Request Data	{"requestData":{"message":"testing"},"requestType":"AdvancedSceneSwitcherMessage","vendorName":"AdvancedSceneSwitcher"}

Receiving messages from the scene switcher in external tools via websocket events

An example event emitted by the Advanced Scene Switcher containing the message "testing" would be the following:

{
    "d": {
        "eventData": {
            "eventData": {
                "message": "testing"
            },
            "eventType": "AdvancedSceneSwitcherEvent",
            "vendorName": "AdvancedSceneSwitcher"
        },
        "eventIntent": 512,
        "eventType": "VendorEvent"
    },
    "op": 5
}

Sending OBS websocket messages (not specific to the advanced scene switcher)

You will have to construct the message body in accordance with the OBS websocket protocol.
So you your message must at least include an op and d field and in most cases also the requestId.
Here is an example who to send the websocket message to start a recording: