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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static class`
  `ExternalSourceSelector.SourceData`
  Source (CDN) data container
  `static enum`
  `ExternalSourceSelector.SwitchType`
  The type of the source (CDN) fallback

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ExternalSourceSelector.SourceData`
  `onError(String manifestUrl, Exception error)`
  Called when error occurs during manifest or chunk download.
  `PlayerConfig`
  `onRestart(String manifestUrl, PlayerConfig playerConfig)`
  Called when the restart is needed for the specified manifest URL.

- ## 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