Shaka-player: Update Track documentation

[sanbornhilland]

Branch: master.

I can see that getTracks() has been deprecated in favour of getVariantTracks(). In both cases all the tracks returned are of type variant. However the Track documentation still indicates that the type should be one of video, audio, or text. Which is correct? The documentation or the code?

If you are thinking of moving away from listing the media type, then I think the current deprecation notice won't be sufficient because for people who rely on the type as it is now, this change will already be a breaking change before 2.2 is released.

[TheModMaker]

The getTracks() method will return all tracks (both variants and text tracks). It is being replaced by getVariantTracks() and getTextTracks() which only return the respective tracks. If there are no text tracks, all the tracks will be variant. The warning is because we are removing the method, not because the structure changed.

We also changed what tracks are being returned. Before we returned the individual audio and video tracks and you could choose them separately. Now (in order to support HLS), you can only select by Variants, which is an audio/video pair.

But you are correct, we need to update that documentation.

[sanbornhilland]

O, I see. I understand why it's returning so many tracks now.

I still think that this is going to cause interim problems. getTracks() has been deprecated and will be removed in 2.2. But because the track objects have changed already, this will be a breaking change before version 2.2. If anyone is relying on type being audio or video then these changes will cause problems before 2.2 is released.

[sanbornhilland]

Sorry, I just re-read your comment and I see that you mentioned the deprecation is wrt to the method deprecation and not the track structure change. Which release is the track structure change going to go in?

[TheModMaker]

2.0.x will still return the old structure (with the old behavior) and won't have the new methods or the warning.

2.1.x (and current master) will return the new structure, have all three methods with a warning.

2.2 will remove getTracks().

[sanbornhilland]

Would you be able to provide some additional context as to why the inclusion of HLS necessitates this change to tracks? AVPlayer specifies tracks as audio or video and allows selecting them independently so it's not clear to me that this is a requirement of HLS.

[TheModMaker]

The HLS manifest specifies a set of possible variants that the player can choose from. It does not allow switching between arbitrary streams. So when HLS specifies two variants with different audio and video streams, you can't switch between all possible combinations, only between the variants that were specified.

[joeyparrish]

In particular, we could have split up the audio and video parts of a variant, and we considered doing so early in our HLS implementation. We still stream the independently, so separating the streams themselves is not an issue. But splitting up variants to treat HLS as DASH caused issues with the ABR system.

We used to choose audio and video independently, but HLS only provides a bandwidth value for the combination. There was no way to split them up without making guesses about the proportions. We found that deducing the correct bandwidth for each was complex and we did not always have enough information to do it. Rather than potentially break ABR, we decided to change our internal structures to variants.

Expressing DASH in terms of variants is a trivial transformation by comparison. Unfortunately, those internal changes necessitated changes to our external track objects.

[sanbornhilland]

Great, thanks very much for the context. It's very helpful.