obs-websocket v5.0.0 Development Updates

[tt2468]

Hi all,

I'm starting this thread as a way to share updates on how obs-websocket v5.0.0 is coming along. We have lots planned. (and lots already completed!)

[tt2468]

UI

We've made some big improvements to the UI! I'm particularly proud of this one, as it introduces some features which I think are truly quite groundbreaking. Less talk, more screenshots!

Main Dialog

We've done a total overhaul of the settings page. You can actually do stuff in it now! You've obviously got items from the old design, but I'll describe a few of the new components.

• We've split the dialog into 3 logical sections. This adds better flow to the interface and will help with usability.
• Minor change, debug mode no longer persists across OBS loads (request from OBS devs for technical reasons).
• In 4.9.0, we made authentication enabled by default. However, we would prompt for the user to enter a password on first load, which was really just a quick fix to cover for a realized security issue. Well now instead of prompting for a password, we generate a new one on first load so that users no longer have to do any configuration in order to get fully up and running. We've also exposed that functionality to the UI so that you can easily regenerate a new random password.
• You may notice the Show Connect Info button. I'll get to that in a bit.
• The last section is a new feature we are calling the Session Table. Here, all connected websocket clients are displayed in a live-updating table, allowing you to gain important diagnostic info and statistics, along with the ability to drop (kick) their session if need be.

Connect Info Dialog

Another entirely new feature is the Connect Info dialog. One of the big things we've heard and seen over time is that lots of people (understandably) have issues getting running with obs-websocket. On top of that, some of the most popular tools out there for streaming rely heavily or solely on obs-websocket in order to interface with OBS. This is one of our main objectives in 5.0.0. The result with the current system is that there is a notable learning curve for anything which uses obs-websocket, along with increased time from third-party software developers required to offer support to users who are trying to figure it out. So as a part of our plan to make things simpler for users and developers alike, we've added this dialog as a way to make it easy for users to connect to their obs-websocket server.

• We try to guess the best IP address of the computer, to allow non-local connections. This is definitely not perfect and will need to be improved with more testing
• You can now retrieve your password at any time via this dialog.
  • [Technical Note:] This feature has warranted some technical changes to how obs-websocket stores settings. Previously, the password would be immediately hashed and stored inside your OBS profile, making it unrecoverable. We have changed this to store the password in plain text in the config, which allows us to display it to the user at any time. We are compensating for this inherent security risk by using randomly generated passwords, and prompting the user to avoid using a custom password if they attempt to provide their own.
• Most obviously, we've bundled all of this into an easy to use QR code which can be scanned by devices as a way to connect to obs-websocket. The goal here is to allow users to install obs-websocket, download a mobile app, scan the QR, and be fully ready to go without any need to dig for your password or computer's IP address.
  • [Technical Note:] The format for these qr codes is obswebsocket|[ip]:[port]|[password]. May change. Will update when final decision is made.
    • Example auth required string: obswebsocket|192.168.1.168:4444|ds7scx8f
    • Example auth not required string: obswebsocket|192.168.1.168:4444
• If you click the Show Connect Info button while outputting, you will be asked to confirm that you want to open the window (to avoid accidentally showing the credentials on the feed)

Configuration Storage

We've made some changes to how we store plugin settings which are important for developers to know about.

• All configurations for obs-websocket are back in the global configuration store (previously stored in each profile). The original reason for storing these configs in individual profiles was to allow multiple instances of OBS to be run on one machine, without requiring portable mode. However, storing the configuration in profile had many negative side effects, so we've reverted that change.
• As stated earlier, debug mode no longer persists across loads. This was done to keep users from turning it on, then accidentally leaving it on. Having debug mode enabled can affect performance in cases where lots of messages are flowing, and can make an OBS log almost completely unreadable to readers (Eg. OBS support staff).
• As also stated earlier, the password is now stored in plain text. Another benefit of doing this is that developers making desktop software can implement ways of attempting to automatically configure themselves to connect to obs-websocket. By reading the global.ini file, you can know the port and password of obs-websocket, and attempt to connect using those details. This also allows you to set the password without needing to do it in the UI, though you can only do this while OBS is not running.
• So with all of these changes, we obviously still want to support edge cases where the removed features are still required. For that, we've reimplemented these features as startup command line flags. Using these flags override the saved values without modifying them. It also prevents those values from being changed in the UI.
  • --websocket_port overrides the configured websocket port. Example: --websocket_port=4445
  • --websocket_password overrides the configured authentication password. Example: --websocket_password=supersecure
  • --websocket_debug is a flag which enables debug messages, allowing plugin debug information to be logged during startup when it otherwise would not be.

[tt2468]

Notifications

Notifications have gotten a bit of attention. During the process of porting the notification system over to v5, I discovered that we've actually been doing them wrong the entire time. Realistically, obs-websocket should have been crashing with how big of an f-up it was, but we somehow survived. I'd guess that people did get random crashes from it in 4.x, so sorry about that.

Anyway, here's some screenshots of what we have now.

Connection Notification:

Note that it performs the notification once the client has Identified, not when it first connects.

Disconnection Notification:

Authentication Failed Notification:

I feel like this is one we should have had all along. As I believe, having an incorrect server password set on the client is a very common occurence, and in 4.x, the way the notifications worked would just add to any existing confusion. This should help.

[tt2468]

Request Batches

Warning: This post contains lots of fancy terms. Sorry if it is difficult to read.

Request batches in 4.x were a great addition to the ecosystem. They shine brightly in situations where the connection to OBS is not very fast, or where you want to get "precise" timing on requests. In 5.x, the goal was to further expand on the concept of request batches.

5.x now includes two new "execution types" for request batches, providing new realms of possible use-cases.

Execution types:

• OBS_WEBSOCKET_REQUEST_BATCH_EXECUTION_TYPE_SERIAL_REALTIME (default)
• OBS_WEBSOCKET_REQUEST_BATCH_EXECUTION_TYPE_SERIAL_FRAME
• OBS_WEBSOCKET_REQUEST_BATCH_EXECUTION_TYPE_PARALLEL

---

OBS_WEBSOCKET_REQUEST_BATCH_EXECUTION_TYPE_SERIAL_REALTIME:

• Ideal for processing requests over slower connections, or modifying many scene items (almost) at the same time.
• Basically the same as 4.x request batches.
• Requests are processed in-order
• Requests are processed as soon as possible by one worker thread
• Responses are delivered in-order
• The Sleep request blocks execution for a specified amount of real world time (sleepMillis)

OBS_WEBSOCKET_REQUEST_BATCH_EXECUTION_TYPE_SERIAL_FRAME:

• Ideal for high-precision animation sequences, where syncing websocket requests with frame compositing is important.
• New!
• Requests are processed in-order, just like SERIAL_REALTIME
• Requests are processed on the OBS main graphics thread.
  • BE VERY CAREFUL NOT TO OVERLOAD THE GRAPHICS THREAD WITH LARGE REQUESTS.
  • A general rule of thumb is for your request batches to take a maximum of 2ms per frame of processing.
• Requests processing starts right before the next frame is composited, and the frame is not composited until the batch is completed or a Sleep occurs.
  • This functionality is perfect for things like SetSceneItemTransform
• The Sleep request will halt processing of the request batch for a specified number of frames aka ticks (sleepFrames)
• For developers: The execution of requests gets profiled by the OBS profiler under the obs-websocket-request-batch-frame-tick name.
  • This value (shown in the OBS log after OBS shutdown) represents the amount of time that the graphics thread spent actively processing requests per frame.
  • This tool can be used to determine the amount of load that your request batches are placing on the graphics thread.
• To be clear: If you do not have any sleep requests, all requests in the batch will be processed in the span of a single frame.
• Example use case: Performing a move transition, where a scene item's transform is changed every two frames.

OBS_WEBSOCKET_REQUEST_BATCH_EXECUTION_TYPE_PARALLEL:

• Ideal for lots of processing-heavy obs-websocket requests, like performing SaveSourceScreenshot on 8 sources at once.
• New!
• Requests are processed asynchronously at the soonest possible time.
• Requests are processed by the core obs-websocket thread pool, where the number of workers == the number of threads on your machine.
  • One worker in the pool is always reserved during batch processing for control of the batch execution. This means that if you are using a single core server, this execution type is not supported.
  • Example: If you have 12 threads on your machine, obs-websocket will be able to process 11 requests at any given moment.
• The results array is populated by order of request completion. Consider the order to be random.
• The Sleep request will return an error if attempted to be used in this mode.
• Note: This feature is experimental and can increase the chances of causing race conditions (crashes). While the implementation is fully thread-safe, OBS itself is not. Usage of this is only recommended if you are processing very large batches and need the performance benefit.