search

SRGSSR / srgmediaplayer-apple

An advanced media player library, simple and reliable
MIT License
158 stars 33 forks source link

Provide a way to change subtitles and audio tracks programmatically #64

Closed defagos closed 5 years ago

defagos commented 5 years ago

It is currently possible to change subtitles and audio tracks using the dedicated SRGTracksButton and the associated popover.

An API should provide a way for similar customization in code.

defagos commented 5 years ago

To avoid locking the main thread, it is extremely important never to access asset properties without checking they are loaded first. Media selection options (i.e. subtitles and audio tracks) belong to this category. Assets were previously incorrectly used all over the place, leading to unnecessary hiccups if an asset was not ready while its options were checked.

A first subtitle (and audio track) API based on language codes was introduced. This API was adding a preferred subtitle localization property, which could be set at any time (thus applied when the asset was ready). The actual language selection was made based on this preference, and could lead to a different result (e.g. if the preferred language was invalid or not available).

This API was unnecessarily complex, though, which became especially obvious when attempting to have a consistent behavior with the existing track popover. In such cases, having a preferred language which is can be far away from the actually used language is misleading (especially since the language can be changed as many times as needed afterwards) and reveals a poor API. Reset rules probably would have been required. More documentation than necessary was needed (e.g. the relationship of this API with MediaAccessibility, or the standard to be used for language codes).

For this reason, a new mediaConfigurationBlock has been added, which works in a similar way as the existing playerConfigurationBlock. This block is called once the asset is safe for inspection. The configuration itself can be reloaded or updated at any time as well. The configuration block receives an asset and player item as parameters, which makes it possible to select subtitles or audio tracks using the AVPlayer standard API. No documentation or additional conventions are therefore required.

Moreover, this also has the additional benefit of providing an implementation hook to customize subtitle appearance if needed (AVTextStyleRule).