Add RFC: obs:// URI configuration handling

[coral]

Description

Enable OBS to bind to obs:// URI for simple configuration of RTMP URL & Streamkey.

Motivation

The current setup process from streaming service to OBS is a bit rough for new users, as they must paste a stream key and configure the RTMP URL correctly. The list of services keeps growing and if new services want to onboard onto this list the list will eventually become too long to be meaningful to users.

On top of this streaming services today treat the streamkey as something persistent due to the friction of reconfiguring the streaming settings. Enabling a easier user flow would allow streamkeys and configurations to be more ephemeral, generating a new one per streaming session for example.

Link to RFC

[dodgepong]

Thanks for this RFC! This is something we've been considering for a long time, so I'm excited to get some discussion going around it.

First, I want to be sure to tag @notr1ch, as I know he has some concerns regarding security of URI handlers. Apparently there are several historical examples of other apps' URI handlers having parsing vulnerabilities or weird cross-platform issues that we will have to look out for.

Second, I think for the sake of simplicity, we should focus on an MVP that simply creates a new profile with a given name, sets the Stream Service to Custom, and sets the RTMP URL and stream key. This covers some of the most important cases for letting streaming companies easily get their users set up to stream to their service with OBS. It would be good to think about further usage (video settings, encoding settings, scene/source management, plugin installation) when considering API design, but I think the initial implementation should primarily be concerned with the simple use case of setting up the ingest.

Some additional thoughts:

• If setting the RTMP URL always sets the streaming service to Custom, it is possible that the user may be setting a Custom URL for a service that already exists in the services list. It may be worth it to do a comparison against RTMP URLs in the service list, and if a matching URL is found, set the service to that service instead of leaving it on Custom.
• Should clicking the button to add the service always exclusively create a new profile, or should it ask the user if they want to update the existing profile? Is that too complicated of a question? Also, if it creates a new profile, whose responsibility should it be to name this profile? If it's the responsibility of the service provider, then we'll need a system to automatically handle collisions in case the user already has a profile with the given name.
• Does the API need versioning?
• Regarding obs:// vs. something more generic like streaming://, I'm of two minds. The generic version is obviously more flexible and open to be used by other streaming clients if they are interested in adding support. On the other hand, there are several functions that a URI handler could handle that would be OBS-specific, such as plugin installs, potentially. I'm interested to hear more people's opinion on this, as well as other suggestions as to what the protocol should be named if not obs:// or streaming://.
• Do we anticipate URL payloads ever being larger than the 2048 character limit of a URL? It's possible a huge list of query parameters could get clumsy to generate and handle. Do we want to consider finding a way to send a JSON payload to OBS instead?

[VodBox]

@WizardCM and I had started a doc going over some of what might be in an OBS URI in early 2018. Unfortunately not much was put down besides a few basic examples and commands, but this may be helpful to the discussion as a reference. https://docs.google.com/document/d/1GWSLxtJ91KXQY4HQ0aKG9CisN32GodonNq45Xa7g1E0/edit

[coral]

Answering some questions from @dodgepong .

If setting the RTMP URL always sets the streaming service to Custom, it is possible that the user may be setting a Custom URL for a service that already exists in the services list. It may be worth it to do a comparison against RTMP URLs in the service list, and if a matching URL is found, set the service to that service instead of leaving it on Custom.

Good point, question is if that's needed? It might be needed for Twitch use-cases as you probably want to use the find-ingest API that's being used today. Maybe the URI allows you to define a "service" instead of a rtmpurl such as obs://configure/streaming?service=twitch&streamkey=heregoesmynicestreamkey

Should clicking the button to add the service always exclusively create a new profile, or should it ask the user if they want to update the existing profile? Is that too complicated of a question? Also, if it creates a new profile, whose responsibility should it be to name this profile? If it's the responsibility of the service provider, then we'll need a system to automatically handle collisions in case the user already has a profile with the given name.

How often do people import new configurations? I personally think it's fine to just add more profiles until this use case expands. MVP EXPERIENCE.

Does the API need versioning?

Good point, should probably append the RFC to have obs://ACTION/VERSION/VERB?=parameters&=to&=add .

Regarding obs:// vs. something more generic like streaming://, I'm of two minds. The generic version is obviously more flexible and open to be used by other streaming clients if they are interested in adding support. On the other hand, there are several functions that a URI handler could handle that would be OBS-specific, such as plugin installs, potentially. I'm interested to hear more people's opinion on this, as well as other suggestions as to what the protocol should be named if not obs:// or streaming://.

You're asking for other people's opinions here so it's weird that I'm answering again but I spent some time thinking and I think going with obs:// is a great start. If this scheme catches on nothing limits using a more generic streaming:// in the future. I think if OBS makes this it serves as a good example of where the industry could move, which opens up the discussion for a generic protocol.

Do we anticipate URL payloads ever being larger than the 2048 character limit of a URL? It's possible a huge list of query parameters could get clumsy to generate and handle. Do we want to consider finding a way to send a JSON payload to OBS instead?

Don't anticipate this being an issue for the MVP.

[jp9000]

• Should clicking the button to add the service always exclusively create a new profile, or should it ask the user if they want to update the existing profile? Is that too complicated of a question? Also, if it creates a new profile, whose responsibility should it be to name this profile? If it's the responsibility of the service provider, then we'll need a system to automatically handle collisions in case the user already has a profile with the given name.

Hm, either way is fine with me really. If we do create new profiles, we should probably let the user know that a new profile was created with a dialog box. If we allow the user to choose to overwrite their current settings vs create a new profile, then a dialog box should come up asking them that. I'm fine with whatever for naming the profile. Either automatically making a new profile name with a specified name or allowing the user to name it themselves.

I think it's somewhat safe to assume this feature won't be used in most cases, so it'd sort of be an "outlying" feature of the problem for the most part, so I feel like we can afford some flexibility in terms of how it's implemented. In other words I'm not going to be too anal about how this is implemented because a very tiny subset of users would probably end up using it compared to most users.

Does the API need versioning?

Probably would be safe to yea.

Regarding obs:// vs. something more generic like streaming://

I'd probably prefer obs://.

Do we anticipate URL payloads ever being larger than the 2048 character limit of a URL?

Could probably pack data in to binary and then convert to/from base64 or something to minimize character usage.

---

I generally approve of this feature as long as we can do it safely and securely. I think the first step is to find someone willing to volunteer making this, starting with at least a prototype like @dodgepong suggested.

[Fenrirthviti]

Motion to enter FCP with disposition merge pending approvals from the rest of the core project team.

Signoffs:
@Fenrirthviti

[Fenrirthviti]

Starting FCP with disposition merge.

[dodgepong]

The URI Scheme would be obs://ACTION/VERB?=parameters&=to&=add

What, exactly, is the difference between an ACTION and a VERB? How do we determine which is which?

Should this RFC contain a proposal for which actions/verbs should be supported in an MVP implementation?

[dodgepong]

To be clear, I'm not entirely in favor of a merge until some of the ambiguities here are cleared up such that someone could use this as a clear roadmap for implementing the feature.

How does the URI handler get installed on each platform? Does this require elevation on macOS, for instance? Will macOS complain and block a URI handler from being installed for some reason if we don't follow a certain set of rules?

Are there any specific security considerations we need to take into account to not expose our users to undesirable behavior? How could an attacker abuse a URI handler to perform something malicious on a users' OBS instance?

[derrod]

Regarding @dodgepong first message; it does indeed seem confusing what a VERB and ACTION are.

The provided examples obs://configure/streaming, obs://install/plugin arguably follow a ACTION/NOUN pattern, whereas the last example obs://scene/add follows a NOUN/ACTION pattern.

These examples could be easily unified to NOUN/ACTION: obs://stream/configure, obs://plugin/install, obs://scene/add.

How does the URI handler get installed on each platform? Does this require elevation on macOS, for instance? Will macOS complain and block a URI handler from being installed for some reason if we don't follow a certain set of rules?

On macOS the URL handler is specified in the applications info.plist (See CFBundleURLTypes), this does not require elevation but I'm not sure if the handler is registered at install time or on first launch.

On Windows you'd have to add it to the HKEY_CLASSES_ROOT registry hive (Registering an Application to a URI Scheme), which may require elevation.

On Linux there seems to be some kind of standard through XDG but I'm not too familiar with it.

Are there any specific security considerations we need to take into account to not expose our users to undesirable behavior? How could an attacker abuse a URI handler to perform something malicious on a users' OBS instance?

As per the RFC:

When I click a link to configure OBS

• I want to a confirmation dialog to confirm my intent

Additionally, the browser itself will also ask for confirmation before actually calling the URL handler. For instance, try opening this link in your browser: steam://console

[Fenrirthviti]

Apologies for the delay on this one, I had thought I already moved us back out of FCP. Seems there is more unresolved discussions to be had here before this can be merged.

[dghodgson]

• Regarding obs:// vs. something more generic like streaming://, I'm of two minds. The generic version is obviously more flexible and open to be used by other streaming clients if they are interested in adding support. On the other hand, there are several functions that a URI handler could handle that would be OBS-specific, such as plugin installs, potentially. I'm interested to hear more people's opinion on this, as well as other suggestions as to what the protocol should be named if not obs:// or streaming://.

Something generic like streaming:// seems a bit presumptuous at this point. If it catches on, it might make sense to support a more generic URI (ideally as a standard with input from other projects). This also discourages other projects from using the same URI with their own specific parameters that OBS might then be expected to handle gracefully.

• Do we anticipate URL payloads ever being larger than the 2048 character limit of a URL? It's possible a huge list of query parameters could get clumsy to generate and handle. Do we want to consider finding a way to send a JSON payload to OBS instead?

I think adding support for JSON payloads is a good idea. Would potentially make automating configuration of OBS easier than it currently is (i.e. importing multiple profiles and scene collections in some cases). All the necessary information could be contained in a single JSON payload instead of split among multiple files.

Not really necessary for an MVP though.

Should this RFC contain a proposal for which actions/verbs should be supported in an MVP implementation?

Yes.

I think the MVP should focus specifically on configuring the Stream settings. Action/Verb nomenclature should be switched for Noun/Verb as that's more consistent.

Output/Video settings might be the next most ideal to tackle (users could click on one of a variety of buttons on a platform's website to have OBS automatically configured with recommended settings for 720p30, 720p60, 1080p30, etc. specific to said platform).

Adding scenes/sources might follow, being used by services that create stream packages for overlays. But a JSON payload might be better suited for this particular use case.

Both of those could be handled via the issue tracker after the MVP is implemented.

[rogueyoshi]

Can you add the ability to add browser sources via URI as well? Since we can already drag URL Shortcuts into OBS, this is the next logical step. This will allow browser source devs to supply configurations as well.

[dodgepong]

This will allow browser source devs to supply configurations as well.

Can you be more specific with what you mean by this?

[rogueyoshi]

@dodgepong Something along the lines of a query string with data to apply transforms, filters, etc.

[Fenrirthviti]

Browser sources are sources like anything else. If we allow passing configuration data for creating a source, we would not need to do anything special for browser sources, so what you are asking for would be possible.

[Conan-Kudo]

FYI: obs:// is a URI handler used by the Open Build Service by various plugins and applications to handle Open Build Service repositories.

[Fenrirthviti]

After internal discussion, and the understand that this RFC is a little old, we aren't sure exactly what the problem this is looking to solve is anymore. Initially, this was an effort to make first-time setup easier, but we have service integrations that have reduced the friction quite a bit.

It might be good to have a restatement of the problem, and what this is intended to solve.

That said, we do still feel there are use cases for this (such as providing a simple link to add a source to OBS, for example), we just want to ensure that there's an overarching problem/solution here rather than just "this would be neat".

[mitchlloyd]

I'm interested in the "add a source" use case as the new MVP. Clicking a link vs copy-paste to add a browser source might not be a huge UX win by itself but it would be great to later support the use case of clicking one link to add several sources.

I'm assuming the new source would be added to the current scene but maybe there's more consideration needed there.