HLS On Shaka Player Migration

Overview

The Cast Web Receiver SDK supports playback of content using several web streaming protocols. Based on the protocol used, the SDK loads a player to handle playback of the content. In the case of HLS content, Media Player Library (MPL) is loaded. In the case of DASH content, Shaka Player is loaded.

Moving forward, the Cast SDK and Shaka Player engineering teams are consolidating efforts to increase support of HLS content playback on Shaka Player. MPL will no longer receive critical updates. We recommend you to opt in to use Shaka Player for your application's HLS content playback.

Shaka Player benefits

In changing players, applications take advantage of the following benefits:

• More robust streaming sessions for users, with improvements in load time failures and latency.
• Continued adoption of the latest HLS features.
• Increased clarity in root cause analysis for player-content compatibility issues due to Shaka Player's open source nature.
• Open source player codebase allows partners to contribute to the Shaka Player Project.
• A significant reduction in feature and bug fix time to production as Shaka Player's release cadence is frequent and independent of the Web Receiver SDK's releases.
• Greater control over the playback environment provided by the shakaVersion API.
• Increased playback support from Google with engineering resources focused on HLS playback on Shaka Player as seen on the roadmap.

Timeline

The Web Receiver SDK will transition to using Shaka Player as the default player for HLS content playback. This will be done in a phased approach to guide partners through the migration process.

The Web Receiver SDK engineering teams are taking a performance driven approach and will only proceed to the next phase when Shaka Player's performance is on par with MPL's baseline performance. These changes will be announced in the cast-sdk-announcements google group and updated in this guide.

Opt in

Starting with CAF version 3.0.0105, there is an application level configuration to opt-in to use Shaka Player for HLS playback. This version also introduces an API to select from a supported range of Shaka Player versions to load. These flags are provided in the CastReceiverOptions class through the useShakaForHls and shakaVersion properties and are evaluated when the CastReceiverContext is started. Any application opting in to Shaka for HLS should set a Shaka Player version of at least 4.3.4 to take advantage of the latest HLS improvements. To opt-in, follow the code snippet below:

const context = cast.framework.CastReceiverContext.getInstance();

let castReceiverOptions = new cast.framework.CastReceiverOptions();
castReceiverOptions.useShakaForHls = true;

context.start(castReceiverOptions);

Validate content

Partners should validate their content playback on Shaka Player prior to opting in to use Shaka Player in their production app. We recommend testing for each of the variations in your content listed below:

• Stream types: LIVE or VOD
• Container formats: TS, MP4, or elementary streams
• Content with discontinuities or embedded ads
• Playback on the following device types: smart displays, Chromecast dongles, Android TV devices, TV's with Chromecast built-in, smart speakers

If you find any errors or unexpected behavior, file a bug. Once you are able to verify that there are no critical playback failures in your content, push the changes to your production environment.

Opt out

The Web Receiver SDK will transition to an opt-out model for Shaka Player HLS content playback according to the timeline. The property useShakaForHls will change its default value from false to true. At that time, applications can elect to use MPL for HLS playback by manually setting this property to false. When the CastReceiverContext is started, the Web Receiver SDK will revert to loading MPL instead of Shaka Player. See the sample below for how to opt-out:

const context = cast.framework.CastReceiverContext.getInstance();

let castReceiverOptions = new cast.framework.CastReceiverOptions();
castReceiverOptions.useShakaForHls = false;

context.start(castReceiverOptions);

Report issues

We encourage our partners to file any issues that they find when playing HLS content. As mentioned, MPL will no longer receive critical updates. If any issues are encountered with MPL, follow the steps in the Opt in section of the guide to verify if switching to Shaka Player will unblock your issue. Follow the steps below if the issue is still present or if you encounter a different issue when switching players.

1. Try setting the shakaVersion to a different branch version to resolve the issue. For example, if the issue is experienced on the 4.3 branch, try setting it to the latest release in the 4.2.x or 3.3.x versions. Check the Shaka Player release notes to find releases with the most relevant updates. Note that the shakaVersion API has a minimum and maximum supported version as detailed in the reference documentation. If you observe that there is a regression, report the issue in the Shaka Player issuetracker.

2. Try changing the player configuration parameters. Shaka Player is configurable through the PlayerConfiguration object. The Web Receiver SDK defines a set of default values and enables applications to modify this configuration through the shakaConfig property in the PlaybackConfig object. This is evaluated during load time when the player instance is created. See more in

   application configuration and options. The default values set by the Web Receiver SDK are the recommended values.

3. See if the issue has been reported in the Shaka Player issuetracker or the Cast issuetracker. Comment on the bug and add any relevant information if it describes your issue as well.

4. Test your content on the Shaka Player demo site. If you find that the issue reproduces in the demo site for your content, file a bug with the Shaka Player project.

5. File a bug in the Cast Issue Tracker if you have an issue unique to Shaka Player on cast endpoints.

FAQs

Changing players can stir up a lot of questions. Below you'll find the most common questions answered to help guide you through the migration process.

Should I migrate to Shaka Player?

We encourage our partners using HLS content to begin the migration process as soon as possible. As a result, your app will provide a more robust streaming experience for your users. More benefits are outlined in the Shaka Player benefits section of this guide. Partners should verify that their apps are working properly using Shaka Player to ensure a smooth transition. Some apps may be at risk for when the Web Receiver SDK transitions to an opt-out model if partners don't verify that their content plays properly on Shaka Player ahead of time.

What is the expected level of effort when changing players?

Partners will need to test their application and content in a test environment to ensure that the user experience is similar or improved when compared to HLS. To do this, partners will need to opt-in to the feature in an internal environment and thoroughly test that their content is able to play using Shaka Player. See validating content for details on what aspects of your content to focus on. Once validated, partners will need to add the flag to opt-in in their production application environment to start taking advantage of the benefits provided by Shaka Player. At a high level there are minimal software development changes and mostly QA requirements for our partners to successfully migrate.

My application will soon use HLS to stream content, what should I do?

New integrations should opt-in to use Shaka Player for playback. Your application will be supported better in the long term and will also take advantage of the new HLS features and performance improvements. If your new integration is experiencing issues, file a bug as soon as possible to give the engineering team enough time to resolve the issue. If your application has a tight deadline, include that information in the bug report as well as the impact to prioritize accordingly. Our engineering team will work to provide a solution to adequately support your users.

My content or app doesn't work with Shaka Player, what now?

You should file a bug with either the Shaka Player Project or the Cast project (see Report issues). The Cast SDK engineering team is actively monitoring these trackers and will work with you to resolve any issues at hand. The earlier that these issues are detected, the more time they will have to deliver a fix.

MPL is no longer receiving critical updates, what exactly does that mean?

Historically, MPL has adopted new HLS features and patched major bugs through critical updates. Now that MPL will no longer be receiving them, new HLS features won't be added to the player. Likewise, any reported issues for HLS playback on MPL won't be fixed in MPL. These issues should be resolved by switching to Shaka Player for playback. If issues persist, then a bug should be filed with the relevant issue(s) faced on Shaka Player. Partners should move away from using MPL.

My content uses the Smooth Streaming protocol, how does this affect my application?

The MPL binaries will still be hosted and accessible to your receiver application. However, any Smooth Streaming related feature requests and bug fixes won't be supported as the Smooth Streaming specification has not been updated in over four years. We recommend migrating your content to use the DASH or HLS streaming protocol to continue receiving performance updates and support for your content.

My content doesn't use the HLS or Smooth Stream protocols, how does this affect my application?

If your content library doesn't use either of those streaming protocols, then you won't be impacted by the migration. No changes are required in your application.