add getSceneItemList, getSceneItemTransform & getBrowserInputSettings…

[deemonrider]

This is a follow up to: #499 as the previous approach failed when duplicating a browser source reference.
This time I tried to stay with the implementation more closely with how the WebSocket handles it and giving developers the same flexibility.

Description

This new feature adds:

• getSceneItemList

• getSceneItemTransform

• getBrowserInputSettings

Motivation and Context

I was really shocked to discover that this feature doesn't exist. Thinking about what information a browser should be able to read out, this would be my first thought:

1. Missing essential information: window.outerWidth / screen.width or similar tells you the size of the browser source itself BUT not if a user messed up the aspect ratio or scaled down the source via transforming. Currently, the only way to get this information is by using the websocket. This leads to the next big issue:
2. HTTPS websites can't access a non-secure Websocket: When providing browser sources to streamers, they are usually all served via HTTPS— The issue? Mixed Content. When serving the Browser Source via HTTPS, we can't access the non-secure websocket. This means I would need to host a separate HTTP overlay just to be able to read out how my source is configured. Serving a browser source without HTTPS is no longer acceptable and will discourage users, as HTTP is widely considered insecure.
3. Least Privilliges: Additionally, WebSockets grant me full rights to do whatever I want—technically. So as a user, you wouldn't really want to have that enabled just to read out some basic information. This implementation is read-only and can't harm anyone but provide essential value.

I decided to bundle these three functions into a single PR since they are closely related:

• First, you can call getSceneItemList to retrieve all items in a scene.
• Next, use getBrowserInputSettings to identify which of those items are relevant.
• Finally, you can fetch the transformation details for each item individually using its unique ID.

How Has This Been Tested?

Environment: Windows 11 x64, OBS Studio 31.1.2 (build 104)

• I've used the buildin obs debugging tool to access the console and compare the output to the settings I've changed of the browser source and then called in the console:
• I've tested the permission behavior handling if the user removes all permissions of the browser source -> returns null like the other functions.
• I've duplicated a browser source so I have two times the object in my sources to ensure this is working now aswell.

Types of changes

New feature (non-breaking change which adds functionality)
Documentation (a change to documentation pages)

Checklist:

• My code has been run through clang-format.
• I have read the contributing document.
• My code is not on the master branch.
• The code has been tested.
• All commit messages are properly formatted and commits squashed where appropriate.
• I have included updates to all appropriate documentation.

[deemonrider]

Hi! Just checking in to see if there’s anything I can do to help get this PR reviewed :)

I’m happy to split the functionality into smaller PRs or make any changes needed to align with project expectations, just let me know what needs to be done!

Thank you and thanks a lot for maintaining the project.

[Fenrirthviti]

At a glance there doesn't seem to be anything major that you need to do.

We review things as we have time, resources, and as priorities allow.

[MattIPv4]

👋 Hey friends, super interested in this as it'd unlock quite a bit for us with automating scene layout bits within a browser source. Anything I can do to help move this forward?

[MattIPv4]

Would love to see transform (or at least position) information included for these, if that would be possible?

[deemonrider]

I built the feature as closely as possible to the existing WebSocket implementation, and that implementation does not include this.

I also don’t think this needs to be added directly to SceneItem:

With my implementation, you can first retrieve a scene item and then call getSceneItemTransform to get everything you might need: position, rotation, scale, bounds, and even whether it’s cropped (see screenshot 2 above).

[MattIPv4]

Ah sorry I completely missed that getSceneItemTransform exposes all the scene items and not just the browser source itself!

[jonaswagern]

I would love to have this also. Bump

[paul-lrr]

I see that this change allows a browser source to get a list of all the items in a scene, but how would it get its own name and/or sceneItemId? From what I understand, it needs that Id in order to get its own info from getSceneItemTransform and getBrowserInputSettings

[deemonrider]

I see that this change allows a browser source to get a list of all the items in a scene, but how would it get its own name and/or sceneItemId? From what I understand, it needs that Id in order to get its own info from getSceneItemTransform and getBrowserInputSettings

Call getSceneItemList() to get all items in the scene.

Iterate over them and call getBrowserInputSettings(sceneItemId) on each — the returned settings include the url property, which you can compare against your own window.location.href to identify yourself.

(There can be a scenario where a user duplicates a browser source in the same scene where you would end up finding twice or more sources with the same href - but that could and should also be handled easily, if you detect your own href is twice in the scene list -> show error message to the user. If its onces in the lists - its yours. Usually you also don't want to have users add your browser sources more than once per scene - so you can even prevent them to do that with this update.)

[paul-lrr]

Call getSceneItemList() to get all items in the scene.

Iterate over them and call getBrowserInputSettings(sceneItemId) on each — the returned settings include the url property, which you can compare against your own window.location.href to identify yourself.

(There can be a scenario where a user duplicates a browser source in the same scene where you would end up finding twice or more sources with the same href - but that could and should also be handled easily, if you detect your own href is twice in the scene list -> show error message to the user. If its onces in the lists - its yours. Usually you also don't want to have users add your browser sources more than once per scene - so you can even prevent them to do that with this update.)

Ah, ok. so similar to how you would do it with obs-websocket. I was asking because a browser source having easy access to it's own name/source ID is something I've been hoping could be added to obs-browser for a long time. It would be very useful to have a source able to manipulate itself with the new functions in this PR or via obs-websocket without having to go through and check all the urls.

FWIW, I do actually sometimes find it useful to have multiple browser sources in a scene that are separate sources but have the same url. For instance, having sources of the same page but with a different browser size to use in different circumstances or having sources of the same url using query strings that may currently be the same but have the option to be different.