Package com.castlabs.android.player

Interface ExternalSourceSelector

All Known Subinterfaces:
SourceSelector
public interface ExternalSourceSelector
The interface defines the source (CDN) fallback selection. Note however that the alternative manifest(s) can also be hosted on the same CDN node if needed as per a custom scenario. See also InternalSourceSelector to handle multiple base URLs defined in the manifest.

The onError(String, Exception) is called whenever a manifest or segment download failure occurs and the implementation needs to decide whether to proceed with the fallback by providing a ExternalSourceSelector.SourceData with the fallback data or the playback shall generate an error and stop (by returning here null). This callback is executed within a dedicated thread not to block neither the playback nor the main threads, thus giving additional flexibility for the implementation to execute time-consuming actions. When the ExternalSourceSelector.SourceData is provided, the playback tries to switch to the new CDN by downloading corresponding manifest and updating the player model ('soft' restart)

If for any reason the player model can not be updated (e.g. the number of representations or adaptations mismatch), then the onRestart(String, PlayerConfig) is called to decide whether to do a full playback restart with the newly provided PlayerConfig with fallback data ('hard' restart) or to stop the playback and generate an error.

Note that the playback re-tries to download both manifest and segments according to NetworkConfiguration before executing the fallback mechanism.

Note that upon 'hard' restart the playback tries to keep the playback position, volume, manually selected video quality based on bitrate (if any), audio and text selections based on the language.

The implementation of the current interface has to be installed into the PlayerController.setExternalSourceSelector(ExternalSourceSelector) in the following way: 


                ...
                // (Optional) Install the CDN fallback implementation
                playerView.getPlayerController().setSourceSelector(new SourceSelector() {
                        public SourceData onError(@NonNull String manifestUrl, @NonNull Exception error) {
                                // Have the fallback CDN only for one particular URL
                                if (manifestUrl.equals("https://demo.cf.castlabs.com/media/QA/QA_BBB_single_4/Manifest.mpd")) {
                                        return new SourceData("https://demo.cf.castlabs.com/media/QA/QA_BBB_single_2/Manifest.mpd");
                                }
                                // No fallback CDN for other URLs
                                return null;
                        }

                        public PlayerConfig onRestart(@NonNull String manifestUrl, @NonNull PlayerConfig playerConfig) {
                                // Do the 'hard' restart for the selected URL when the 'soft' one fails
                                if (manifestUrl.equals("https://demo.cf.castlabs.com/media/QA/QA_BBB_single_4/Manifest.mpd")) {
                                        // Simplify here and just update the currently failed player config with the fallback CDN URL
                                        // Usually, ensure that the DRM and other player config parameters are valid for the
                                        // returned player config or create a completely new player config
                                        return new PlayerConfig.Builder(playerConfig)
                                                        .contentUrl("https://demo.cf.castlabs.com/media/QA/QA_BBB_single_2/Manifest.mpd")
                                                .get();
                                }
                                // No fallback CDN for other URLs
                                return null;
                        }
                });
                ...
Since:
4.2.38

  • Method Details

    • onError

      @Nullable ExternalSourceSelector.SourceData onError(@NonNull String manifestUrl, @NonNull Exception error)
      Called when error occurs during manifest or chunk download. The selector implementation may decide to proceed with the CDN fallback and provide the fallback CDN data as a return value

      Called on the dedicated thread so that the playback thread is not blocked

      Parameters:
      manifestUrl - The failed manifest URL
      error - The error occurred
      Returns:
      The fallback CDN data or null for the player to generate the error and stop

    • onRestart

      @Nullable PlayerConfig onRestart(@NonNull String manifestUrl, @NonNull PlayerConfig playerConfig)
      Called when the restart is needed for the specified manifest URL. The implementation shall either provide the PlayerConfig to proceed with the restart or null for the playback to generate the error and fail

      Called on the playback thread

      Parameters:
      manifestUrl - The manifest URL for which the PlayerConfig is required
      playerConfig - The currently playing config, which is to be replaced with the requesting one
      Returns:
      The PlayerConfig or null for the player to generate the error and stop