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 class` | `ExternalSourceSelector.SwitchType` | The type of the source (CDN) fallback

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    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 Detail

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