09. WebSocket Portal for OBS
The WebSocket Portal (hereinafter referred to as “WS Portal”) allows remote control of OBS Studio over the Internet.
Since obs-websocket is used as the communication protocol, you can use any third-party client that supports the obs-websocket protocol, such as OBS-web, OBS Blade or Deckboard etc.
There is no need to open router ports, tunneling or VPN. There is also no need to give out your home public IP address.
Simply create a WS portal in the SRC-Link Control Panel and link to it from OBS Studio with the SRC-Link plugin installed, and a URL will be issued that you can connect to from the Internet.
Motivation
The requirement that OBS Studio not be a web server that could be accessed by an unspecified number of clients during streaming led to the development of WS Portal. We want to avoid exposing the port to the Internet, even though it is password-protected.
We also wanted to support TLS transmission. Not only OBS, but also vMix and SRT MiniServer with Web controllers are almost all TLS-unsupported.
SSL tunneling as guided in the official documentation is ultimately the same as exposing the port.
Furthermore, when controlling OBS Studio with the SRC-Link Control Panel, it is reasonable to adopt the obs-websocket protocol. The WS Portal is a byproduct of the development process.
- obs-websocket protocol compatible server that can remotely control OBS Studio via the Internet
- Secure remote control over the Internet without opening the OBS Studio port
- TLS transmission support
- Compatible with obs-websocket protocol, so you can connect with existing obs-websocket clients
- Supports obs-websocket JSON (text) protocol as well as MessagePack (binary) protocol
- Set a dedicated login password for the WS Portal
- WS Portal can be shared by the operation team. Remote control of staff's OBS Studio is possible.
- Client connections can be managed via the SRC-Link control panel
- Screenshot cache (to be implemented)
Q. Is WS Portal a relay server?
A. WS Portal is an obs-websocket protocol compatible server. It interprets requests and sends them to OBS Studio, and sendback from OBS Studio to the client via the obs-websocket protocol. Therefore, the behavior will not be 100% equivalent and may not work for some clients.
- Remotely control OBS Studio with a smartphone or tablet at remote events or outdoor broadcasts. (Basic operations such as start and end of broadcast, easy switching, and monitoring are available)
- Workflow to allow online volunteers to remotely control OBS Studio at an event
- Workflow in which the OBS Studio to be handled changes from case by case (can manipulate without having to change the client-side connection)
- Develop web apps or services that interact directly with OBS Studio
- Integration with IoT devices
- Automatic control of broadcasting
For now, what can be achieved with the WS Portal conforms to the obs-websocket protocol, but SRC-Link itself is expected to provide more advanced control through additional functionality.
A list of obs-websocket compatible clients can be found in the obs-websocket GitHub repository.
The developer has mainly tested the working with OBS-web and OBS blade.
First, create a portal on the SRC-Link Control Panel that will serve as an obs-websocket compatible server.
-
Log in to the SRC-Link Control Panel and open the “WS Portals”.
-
Click on “Create Portal"
-
Set each input field as follows
-
Name: Name of portal
-
Description: (Optional) Enter a description of the portal. It will be displayed in detail and can be used as a memo.
-
Picture: (Optional) You can upload decorative images that add a bit of color to your workspace, which are displayed in detail.
-
Password: Generate and enter the password that the obs-websocket client will use to connect to the WS Portal. This is not the password for the OBS standard WebSocket server. The WS Portal does not use the OBS standard WebSocket server, so please enter a different password.
You will not be able to check your password later on the site, so you should remember what you have entered or write it down.
-
Location: As for the server location selection, currently only “North America” can be selected.
-
Event Subscriptions: Select OBS Studio events which you would like to receive on WS Portal. The requirements vary depending on the obs-websocket client product, but in particular, events marked with “*” are “high-volume events”.
For now, it is OK with everything selected, and if the OBS becomes too sluggish, turn off the high-volume events.
-
Block Screenshot Request: If checked, “screenshot taking requests” are prohibited to obs-websocket clients connecting to this portal.
If you block the screenshot request, the client will not see the preview image.
-
Authorized Teams: (Optional) Select an operation team that has access to the WS Portal. Share the portal with your operation team so that you can link your operator's OBS Studio to the portal (The obs-websocket client can be connected to by anyone who knows the address and password)
The following is what you can do for each role
- Admin role: Can manage connections, modify portal. abilities to link OBS Studio to the portal
- Staff role: Can inspect portal, abilities to link OBS Studio to the portal
-
-
Click “Save”
The WS Portal is now created and ready to be linked from OBS Studio, and obs-websocket clients are ready to be connected.
The WS Portal by itself accepts connections from obs-websocket clients, but it requires OBS Studio to be linked in order to use it, so link OBS Studio first.
Link OBS Studio to the WS Portal so that it can be manipulated by the obs-websocket client.
The following assumes that the SRC-Link plugin is already installed in OBS Studio and that you are logged in
-
Click on “WebSocket Portal” from the “Dock” menu
-
The “WebSocket Portal” dock will appear. Select the WS portal you wish to link from the “OBS WebSocket Portal” combo. The combo shows both portals owned by you and shared by your team.
-
Upon selection, the connection is made immediately and the status display changes to green “Linked”.
This completes the link to the WS Portal.
Since the OBS standard WebSocket server is not used, the WS Portal works regardless of whether it is enabled or disabled. Therefore, it is safe to disable this.
Note that obs-websocket itself is necessary because the API is used.
Connect to the WS Portal with any obs-websocket client and manipulate the linked OBS Studio.
OBS-web is an obs-websocket client that allows you to easily control OBS Studio in your browser （GitHub Repository）
-
Log in to the SRC-Link Control Panel and open the “WS Portals”.
-
From the list of portals, select the portal you wish to connect to; if there is only one, it will remain selected.
-
Click on the “Connection Info” button in the upper right corner
-
The dialog displays connection information.
- Address: The DNS name of the server.
-
Port: Port number (usually
443) -
URL: URL format starting with
wss://. Copy and pace this URL for OBS-web. - Password: The password will not be displayed, so please use the one you remembered or wrote down when you created the portal.
The above information is for clients with TSL capability; OBS-web has TLScapability.
For clients that do not support TLS connections, click “Non-TLS Connection info (Not recommended)” Non-TLS connections are not recommended because they do not encrypt communications.
-
Open OBS-web and paste the URL beginning with
wss://that you just copied into the upper input field. -
Please enter your password in the bottom row.
-
Click the “Connect” button.
When the connection is successful, the image will appear in the preview. Switching is also possible by clicking on the buttons provided for each scene or the “cut” and “fade” buttons.
OBS Blade is a remote control app that runs on smartphones and tablets. （GitHub Repository)
-
First, as in the OBS-web case, log in to the SRC-Link Control Panel and open the “WS Portals” to obtain connection information.
-
Install OBS Blade on your smartphone or tablet.
-
Launch OBS Blade, tap the “Aa” button, then tap “Domain
-
Under “Hostname”, select
wss://in the combo on the left end and enter the address obtained from the SRC-Link Control Panel in the input field to the right -
Enter the port obtained from the SRC-Link Control Panel in “Port” (usually
443) -
Enter the WS Portal's password in the “Password” field.
-
Tap the “Connect” button
When the connection is successful, the OBS Blade dashboard will appear. Tap “Current OBS scene preview” to preview the program out.
Client connections can be listed and deleted in the SRC-Link ControlPpanel (for team shares, only admins can delete them)
The steps for deleting a client connection are as follows
-
Log in to the SRC-Link control panel and open the “WS Portals”.
-
Select a portal from the list; if there is only one, it will remain selected.
-
Click on the “trash can” icon in the list to remove unwanted connections.
Since the WS Portal is designed to be accessed over the Internet, it has the following limitations compared to the OBS standard WebSocket server.
-
Screenshot Request:
Consecutive requests for the same source that last less than one second are blocked; they arrive at OBS Studio at one-second intervals, throttled.
-
High-volume events:
High-volume events are sent at a predetermined interval. As an example, the
InputVolumeMetersevent will be throttled to about 0.25 seconds in the WS portal. -
connection timeout
If no data is sent or received for 2 hours, the system times out and disconnects. The clients should send ping every some intervals.
-
Limitation on the number of connections
There is a limit to the number of simultaneous connections per portal. Multiple clients can be connected to a single portal, but the number of simultaneous connections cannot be exceeded.
It is also possible to force disconnection from the SRC-Link Control Panel (see Troubleshooting below).
-
Bandwidth limitations
Internet outbound bandwidth from the WS Portal is limited to a level for general use (Around 5Mbps~8Mbps)
-
Latency
Latency may exist in some areas because the server is located in North America (around 200ms from Japan)
-
Compatibility with obs-websocket
100% compatibility is not guaranteed and some clients may not work.
| Requests, Events | Throttling interval (ms) | Delay (ms) | Remarks |
|---|---|---|---|
| GetSourceScreenshot | 1000 | 0 | per source |
| InputVolumeMeters | 250 | 0 | |
| InputActiveStateChanged | 250 | 0 | |
| InputShowStateChanged | 250 | 0 | |
| SceneItemTransformChanged | 250 | 0 |
(*) During throttling, the first request event and the last request event are output and ignored in between.
Message and event size： Limited to a maximum of 2MB per message event.
See the obs-websocket protocol documentation for details on request events.
- Nothing is displayed when I connect with the client.
OBS Studio may not be linked to the portal.
First link OBS Studio to the portal, then connect or reconnect to the portal with the client.
- I'm not doing anything and I get disconnected regularly in 2 hours.
If no data is sent or received for 2 hours, the system times out and disconnects.
If your client is not sending pings regularly, you will need to perform some sort of operation at least once every two hours.
- Cannot connect even though the address and password are correct.
The maximum number of connections may have been reached. Unnecessary connections can be deleted in the SRC-Link Control Panel.
Possible situations:.
It is possible that the client has not released the connection due to some malfunction. Or a single client may be using multiple connections simultaneously.
Terminating the causing client will also release the connection.
- OBS Blade previews that play smoothly on LAN connection are lagging, and images are delayed when switching.
It is a specification because screenshots are taken and displayed at a coarse interval of 1 second.
- Audio volume meter on OBS Blade is choppy
It looks choppy because the WS Portal is throttling the InputVolumeMeters events to 0.25 second intervals.
- No sound
WS Portal (obs-websocket protocol) does not have the ability to receive audio.
- Screenshot preview is not displayed
You may have blocked screenshot requests in your portal settings.
- Some clients do not work via WS Portal
We will investigate what we can, so please let us know via GitHub Issue, etc.
(*) If it's a paid client, we may not be able to confirm this.
If it works fine with the OBS standard WebSocket server, but not via the WS Portal, it may be a compatibility issue with the WS Portal.
- Unexpected disconnection
In the case of a browser-based client such as OBS-web, the browser's optimization mechanism may stop the page operation when the tab is inactive for a certain period of time. Therefore, WebSocket connection will also stop temporarily, and the client will be disconnected from the server.
This is a normal behavior caused by the browser's optimization feature, so please reconnect the client.
When the WS Portal server restarts, client connections are also disconnected (WS Portal servers may be restarted for maintenance, etc.).
In addition, some clients are implemented in such a way that when OBS Studio terminates, it also terminates own connection (OBS Blade is a case in point).