Add RFC: Protocol API

Author: tytan652

text/0045-protocols-in-outputs-api.md

@@ -0,0 +1,103 @@
+# Summary
+
+- Add notion of protocol in service outputs and services
+- Those outputs are registered with a list of compatible codecs
+- Show stream services or their servers that have the needed protocol registered
+- Show only stream encoders compatible with the selected outputs
+- Add as byproduct the possibility to add plugin with new service output with a new protocol (useless without [RFC 39](https://github.com/obsproject/rfcs/pull/39))
+
+# Motivation
+
+Create a better management of outputs, encoders and services with a protocol centered approach.
+
+Byproduct: Add also the possibility to support third-party plugin which add protocol support with his own output.
+
+*Services addition is a part of [RFC 39](https://github.com/obsproject/rfcs/pull/39).*
+
+# Design
+*This RFC does not consider that because a protocol support a encoder it should be implemented in the main project.*
+
+## Outputs API
+**This only mainly concern outputs with the flag `OBS_OUTPUT_SERVICE`.**
+
+Adding to the API those fields:
+- `protocols`: protocols "official" acronym (ex: RTMP, WebRTC)
+- `protocols_prefixes` (optional): for custom service detection (eg `rtmp://`, `srt://`)
+
+
+If an output support various protocol like `;` should be used as a separator between them (e.g `"RTMP;RTMPS"`, `"SRT;RIST"`). Same for prefixes (e.g `"rtmps://;rtmp://"`, `"srt://;rist://"`).
+
+Adding to the API those functions:
+- `bool obs_output_find_protocol(const char*)`: return true if an output with the protocol is registered
+- `obs_output_enum_types_with_protocol` return outputs corresponding to the protocol
+- a way to enum prefixes and/or a way to find protocol based on the prefix so `obs_output_enum_protocol_prefix` and/or `obs_output_find_protocol_with_prefix`
+
+Protocols like SRT or RIST are codec agnostic so, we need to add 3 new flags:
+- One indicating that the output is video codec agnostic.
+- One indicating that the output is audio codec agnostic.
+- One combining the two.
+
+If not `encoded_video_codecs` and `encoded_audio_codecs` will be required.
+
+### About Protocols
+`encoded_video_codecs` and `encoded_audio_codecs` shall contain any codec compatible with the protocol following their specification. Except RTMP(S), it will only support H.264 and AAC for now.
+
+It does not mean that services are compatible with all the codecs present in the specs. And neither mean that OBS shall support those codecs.
+
+The actually supported protocol with their specification documents :
+- RTMP (https://wwwimages2.adobe.com/content/dam/acom/en/devnet/rtmp/pdf/rtmp_specification_1.0.pdf)
+- RTMPS (same as RTMP)
+- HLS (https://datatracker.ietf.org/doc/html/rfc8216)
+- SRT (https://github.com/Haivision/srt/files/2489142/SRT_Protocol_TechnicalOverview_DRAFT_2018-10-17.pdf ; TLDR: codec agnostic)
+- FTL (no official one found except this https://github.com/microsoft/ftl-sdk/blob/master/README.md)
+
+## Services API
+Adding to the API the field/function `get_protocol`, this will allow services to be multi-protocol.
+
+`rtmp-services` will be modified to not show unsupported services/servers if OBS is not build with RTMPS or FTL support.
+
+And with RFC 39, OBS could prevent showing services where the protocol is not provided by any registered service output.
+And also make services able to not show unsupported protocol if multi-protocol.
+
+We shall consider that if a service handle a protocol, it doens't mean it can handle all the compatible codecs.
+So if a service can't handle all the compatible codec, adding a list of supported codec to a service related to his protocol shall be considered.
+
+Adding to the API those fields:
+- `supported_video_codecs` (optional): sometime stream services don't support all the codec of the specification
+- `supported_audio_codecs` (optional): sometime stream services don't support all the codec of the specification
+
+## UI
+Compatible stream encoders are based on what service can handle and if they specify nothing, any codec accepted by the protocol will be shown.
+
+The user will also be able to choose an audio encoder if various compatible is available with two version of the option simple and advanced.
+
+### Settings loading
+
+Service settings will be load first making stream encoders combobox filled with compatible encoders.
+
+Then the Outputs will be load afterward.
+
+### Service -> Output settings behavior
+
+Changing protocol/output through service change will update the Output page with only compatible encoders.
+
+If the compatible codec is only not available on simple mode, Output settings will be forced switch to advanced mode.
+
+If the service ask for codec not compatible with the protocol, it will be ignored and written in the log as error.
+
+It will reset encoder settings if the actual encoder was not compatible.
+
+The user may need to be warn about the fact that the encoder was not compatible and he need to setup again his encoder.
+
+## What if there is various registered outputs for one protocol ?
+It could happen that a plugin register a output for a already registered protocol, so we need to manage this possibility.
+
+- Add `preferred_output` to the Services API to use what OBS already provide for some protocols with maybe some hardcode in his getter or maybe hardcode the default output per protocol in the UI.
+  - It completely replace `recommended_output` as not a recommendation but as a default choice for output.
+- Add `obs_output_enum_types_with_protocol` return all outputs corresponding to the protocol to the Outputs API.
+- Make the user able also to choose an output if various providing the same protocol are registered (e.g FFmpeg SRT and "Native" SRT) as an advanced options.
+- Deprecate `obs_service_get_output_type` because it got replaced.
+
+# Benefit
+- FTL, if deprecated by OBS and still used by stream services could be separated in a plugin providing the protocol and the output and also service with [RFC 39
+](https://github.com/obsproject/rfcs/pull/39)