Lib vlc options builder

[jdswcz]

Description of Change

Added a builder pattern for LibVLCOptions.

This change introduces a LibVLCOptionsBuilder class to simplify and structure the creation of LibVLC initialization options. The builder provides a fluent, discoverable API for composing commonly used options, improving readability and reducing the chance of misconfigured strings.

Maintains compatibility with old LibVLC constructors to avoid problems for developers when updating to version with this change.

Issues Resolved

Fixes #654 (Parameter --audio-resampler for UWP causes audio to stutter)

API Changes

Added:

• class LibVLCOptionsBuilder
• LibVLCOptionsBuilder AddOption(string option)
• LibVLCOptionsBuilder AddOptions(IEnumerable options)
• LibVLCOptionsBuilder SetVerbosity(int level)
• LibVLCOptionsBuilder EnableDebugLogs()
• LibVLCOptionsBuilder SetAudioResampler(string resampler)
• LibVLCOptionsBuilder SetAudioOutput(string output)
• LibVLCOptionsBuilder DisableVideo()
• LibVLCOptionsBuilder DisableAudio()
• LibVLCOptionsBuilder SetNetworkCaching(int milliseconds)
• LibVLCOptionsBuilder SetFileCaching(int milliseconds)
• LibVLCOptionsBuilder EnableHardwareDecoding(string method)
• LibVLCOptionsBuilder DropLateFrames()
• LibVLCOptionsBuilder SkipFrames()
• LibVLCOptionsBuilder UseXlib(bool enabled)
• LibVLCOptionsBuilder Build() : LibVLCOptions

#if UWP || ANDROID

• LibVLCOptionsBuilder DisableDefaultResampler()
  #endif

• class LibVLCOptions

• LibVLCOptions(string[] options)

• string[] LibVLCOptions.Options { get; }

• static LibVLCOptions LibVLCOptions.Empty { get; }

Removed.

• LibVLC.PatchOptions()

Platforms Affected

• Core (all platforms)
• iOS
• Android
• UWP

Behavioral/Visual Changes

None

Before/After Screenshots

Not applicable

Testing Procedure

• Verified that LibVLCOptionsBuilder produces correct and expected LibVLC option strings
• Confirmed that usage of the builder allows to avoid problematic parameter --audio-resampler=speex_resampler" on UWP

PR Checklist

• Rebased on top of the target branch at time of PR
• Changes adhere to coding standard
• New API is documented and tested

[mfkl]

Thanks for the contribution!

I'm gonna need some time to review and think if this approach is acceptable, so bear with me please. From an initial glimpse, a few things come to mind:

• https://github.com/videolan/libvlcsharp/blob/3.x/src/LibVLCSharp/Shared/MediaConfiguration.cs some libvlc options can also be configured through the media object. But not all options work through the Media, some only work through the libvlc constructor. The list of options that work with each approach is undocumented.
• libvlc options are officially unsupported, even though many consumers use them. What this means is that there is no guarantee of any API compatibility between major versions. Introducing C# functions as part of the rest of LibVLCSharp (which does follow API best practice, as LibVLC functions do as well) will definitely confuse users. Warnings and docs is necessary, but may not be sufficient.

Let me think about this.. thanks.

[jdswcz]

Thanks for the contribution!

I'm gonna need some time to review and think if this approach is acceptable, so bear with me please. From an initial glimpse, a few things come to mind:

• https://github.com/videolan/libvlcsharp/blob/3.x/src/LibVLCSharp/Shared/MediaConfiguration.cs some libvlc options can also be configured through the media object. But not all options work through the Media, some only work through the libvlc constructor. The list of options that work with each approach is undocumented.
• libvlc options are officially unsupported, even though many consumers use them. What this means is that there is no guarantee of any API compatibility between major versions. Introducing C# functions as part of the rest of LibVLCSharp (which does follow API best practice, as LibVLC functions do as well) will definitely confuse users. Warnings and docs is necessary, but may not be sufficient.

Let me think about this.. thanks.

No worries and take your time. Unfortuantely, I didn't know all the details you mentioned and this is my first PR for LibVLCSharp. Personally, I use libvlc options as well, for example, to configure subtitles design (if libvlc is used to render subtitles).

To clarify my approach: There were originally two LibVLC.cs constructors that already allowed passing any arguments to the libvlc through LibVLCSharp. These were later patched by PatchOptions function while its behavior caused the bug we already discussed. Generally, you are forcing some libvlc options without providing to devs using LibVLCSharp an ability to control the options passed to libvlc. Of course, I could just add some simple parameter to constructor to avoid this behavior. However, I wanted to do it thoroughly. Thus I added builder for libvlc options with support of some basic options as well as adding any generic option user may like. Of course, I kept the compatibility with previous constructors, so updating to new version (in case this PR is approved), won't break current integrations.

Please, consider my PR as concept that should be extended according to https://wiki.videolan.org/VLC_command-line_help/. While I understand (but didn't know in advance) that it is officially unsupported, I believe that using my approach and providing easy to use C# code to build libvlc options will benefit most users and make libvlcsharp integrations easier for everyone.

If you wish, I am willing to help to extend the options builder and document it according to what is (or is not) supported throughout different libvlc versions. I would just need correct information to be able to complete this job.

[mfkl]

this isn't called anywhere, can remove.

[jdswcz]

While I understand your point I would recommend to keep this. If someone wants to instantiate LibVLC class without any parameters, he can just call LibVLCOptions.Empty instead of having to construct new empty options.

[mfkl]

If someone wants to instantiate LibVLC class without any parameters

Then they can just write new LibVLC();