feat(ios): Support for external subtitles on HLS streaming

[danielbady]

Summary

Created a delegate to replace the m3u8 file and add in external subtitle url so that they can be played with the video.
Fixes #1511

Motivation

Allows the use of external subtitles. May also be extended to change the timings of subtitles

[KrzysztofMoch]

Hey, Thank you for your PR!
"Logic" part of this is looking good to me. But I think it's too "intrusive" - I don't like creating PlayerItem just for this feature (as it does not follow convention of codebase). I would create new class for AVAssetResourceLoaderDelegate and some "Utils" class for rest.

[efkann]

Awesome work @danielbady! I wanted to share an issue I encountered while applying a similar custom subtitle implementation. I'm not good with the video terminology but I will try my best.

Some MPEG-TS HLS streams are encoded such that the first video frame doesn’t start at MPEGTS 0. In my case, this caused subtitles to appear roughly 1.4 seconds early. After some investigation, the solution was surprisingly simple — adding the following line immediately after WEBVTT in the VTT file:

X-TIMESTAMP-MAP=LOCAL:00:00:00.000,MPEGTS:126000

Here’s why this matters: MPEG-TS timestamps are expressed in 90 kHz clock ticks, so:

1.4 seconds × 90,000 = 126,000

This tells iOS (AVPlayer) how to align the subtitle timestamps with the video’s internal MPEG-TS timeline. Without it, iOS assumes the video starts at 0, causing early subtitle display. Interestingly, this issue is specific to iOS — web players like Chrome and Android handle the same VTT perfectly without this line.

Even the BAFTA technical spec recommends this approach when subtitles are out of sync:
https://www.bafta.org/wp-content/uploads/2024/09/bafta_view_technical_spec_for_entrants_-_120724.pdf

If subtitles are in sync in Chrome but not in the FireTV app or other browsers, the following should be inserted on the second line, just after WEBVTT, in the VTT file:
X-TIMESTAMP-MAP=LOCAL:00:00:00.000,MPEGTS:126000

Not every HLS stream requires this, but it’s fairly common. I hope sharing this helps others who might run into similar subtitle timing issues on iOS.