Docs

Overview

The Phoenix Media Provider allows an app to easily get Media Entries from the Kaltura Phoenix backend. The app just provides the required parameters and the provider fetches a MediaEntry object ready for use with the player.

Usage

Android (Java)

  // Create a session provider
  final SimpleSessionProvider sessionProvider = new SimpleSessionProvider(BASE_SERVER_URL, PARTNER_ID, KS);

  // Create the media provider
  final PhoenixMediaProvider phoenixMediaProvider = new PhoenixMediaProvider()
          .setAssetId(ASSET_ID) // Required
          .setAssetType(ASSET_TYPE)
          .setContextType(PLAYBACK_CONTEXT_TYPE)
          .setFormats(FORMAT_LIST)
          .setFileIds(FILE_ID_LIST)
          .setReferrer(REFERRER)
          .setSessionProvider(sessionProvider);

  // Load the media
  phoenixMediaProvider.load(new OnMediaLoadCompletion() {
    @Override
    public void onComplete(final ResultElement<PKMediaEntry> response) {
      runOnUiThread(new Runnable() {
        @Override
        public void run() {
          if (response.getResponse() != null) {
            final PKMediaConfig mediaConfig = new PKMediaConfig().setMediaEntry(response.getResponse());
            player.prepare(mediaConfig);
          }
        }
      });
    }
  });

iOS (Swift)

  // Create a session provider
  let sessionProvider = SimpleOVPSessionProvider(serverURL: BASE_SERVER_URL,
                                                 partnerId: PARTNER_ID,
                                                 ks: KS)

  // Create the media provider
  let phoenixMediaProvider = PhoenixMediaProvider()
      .set(assetId: ASSET_ID)
      .set(type: ASSET_TYPE)
      .set(playbackContextType: PLAYBACK_CONTEXT_TYPE)
      .set(formats: FORMAT_LIST)
      .set(fileIds: FILE_ID_LIST)
      .set(referrer: REFERRER)
      .set(sessionProvider: sessionProvider)
      
  // Load the media
  phoenixMediaProvider.loadMedia { (pkMediaEntry.set(refType: .media), error) in
      guard let mediaEntry = pkMediaEntry else { return }

      // Create media config
      let mediaConfig = MediaConfig(mediaEntry: mediaEntry)

      // Prepare the player
      self.player?.prepare(mediaConfig)
  }

Required Arguments

• BASE_SERVER_URL: the backend URL, something like “https://example.com/path/api_v3”
• PARTNER_ID: the partner’s id (integer)
• KS: the Kaltura Session token, or null/nil if the asset can/should play in anonymous mode
• ASSET_ID: the requested asset’s id (String)

Optional Arguments

Fine-grained Media Selection Arguments

• FORMAT_LIST: list of media format strings (project-dependent)
• FILE_ID_LIST: list of file id’s, when the application wants to select a specific file (URL)

Type Arguments

ASSET_TYPE and PLAYBACK_CONTEXT_TYPE depend on the requested use case.

The following are the valid argument combinations:

Service	ASSET_TYPE	PLAYBACK_CONTEXT_TYPE
Linear	Media	Playback
VOD	Media	Playback/Trailer
StartOver	EPG	StartOver
Catchup	EPG	Catchup
Recording	Recording	Playback

To simplify application code, the provider selects the following defaults:

1. If PLAYBACK_CONTEXT_TYPE is not selected, set it to Playback
2. If ASSET_TYPE is not selected:
   • If PLAYBACK_CONTEXT_TYPE is Playback or Trailer, set ASSET_TYPE to Media
   • If PLAYBACK_CONTEXT_TYPE is StartOver or Catchup, set ASSET_TYPE to EPG

As a result, it’s normally enough to just specify PLAYBACK_CONTEXT_TYPE. Recording is the exception.

Note: in special situations an app may also have to set an additional field, assetReferenceType. It should only be used if instructed by Kaltura.

Other

• REFERRER: the application’s referrer string, if relevant.

Error Handling

Following are some cases where client app can listen to the specific error codes and respond based on those. Here KS stands for ‘Kaltura Session’.

Case	Error Code	Error Message
Protected Content with Empty KS	404	Content can’t be played due to lack of sources
Requested Media file type is not present in manifest	404	no available sources for media
Concurrent play limitation	4001	Restricted due to concurrency limitation
KS Expired	601	session token has been expired
Wrong KS	500006	Missing configuration [Partner]
Unexpected Error	“Unavailable”	“unknown error”