Docs | Android

Kaltura Player

On this page:

Overview

Kaltura Player binds PlayKit and its Kaltura-based components as a single master module. As a result, integration is simpler: the Kaltura components don’t need to be specified on build.gradle, they don’t need to be registered, and their configuration is mostly automatic. In addition, Kaltura Player takes care of connecting to the backend to retrieve media playback information, and the app doesn’t need to use the Media Providers.

Player Setup

build.gradle

The basic dependency for build.gradle is the following:

implementation 'com.kaltura.player:tvplayer:4.0.0'

This brings Kaltura Player and PlayKit, and in addition Media Providers, Kava and DTG.

See the Plugins section below for the other plugins.

Player Initialization

To initialize the player, the application has to call one of the following static methods on startup (either in an Application subclass or in a “splash” activity).

In this step the player calls a configuration service on the backend and saves the result.

Note: this step is mandatory when using KalturaOttPlayer and and KalturaOvpPlayer. It’s not used by the KalturaBasicPlayer subclass.

OTT Apps

KalturaOttPlayer.initialize(context, PARTNER_ID, SERVER_URL);

Example:

// From Application or Activity
KalturaOttPlayer.initialize(this, 3009, "https://rest-us.ott.kaltura.com/v4_5/");

OVP Apps

KalturaOvpPlayer.initialize(context, PARTNER_ID, SERVER_URL);
// OR
KalturaOvpPlayer.initialize(context, PARTNER_ID);

Here, SERVER_URL is optional; if not specified, the Kaltura SaaS is used: https://cdnapisec.kaltura.com.

Player Creation

To create a player, first create a PlayerInitOptions object, passing the partner id to the constructor:

PlayerInitOptions playerInitOptions = new PlayerInitOptions(PARTNER_ID);

This class has many properties/settings – some of them were previously on PlayKit’s Player.getSettings(), and some are new.

See Player Settings below for the list of options.

Creating the Player

OTT

KalturaPlayer player = KalturaOttPlayer.create(context, playerInitOptions);

OVP

KalturaPlayer player = KalturaOvpPlayer.create(context, playerInitOptions);

Other

KalturaPlayer player = KalturaBasicPlayer.create(context, playerInitOptions);

Prepare the View

Before loading media into the player, the view used to display the video should be set to the size that matches the application use case. This is done by calling player.setPlayerView(), passing width and height. Commonly this would be:

player.setPlayerView(FrameLayout.LayoutParams.MATCH_PARENT, FrameLayout.LayoutParams.MATCH_PARENT);

Next, add the player view to the view hierarchy:

ViewGroup container = findViewById(R.id.player_root);
container.addView(player.getPlayerView());

Load Media

OTT and OVP Players

The Media Providers are now built-into the player. As a result, they are managed by the player and the application just have to pass the parameters to the player.

This is done by creating a subclass of MediaOptions object, setting its properties, and passing it to player.loadMedia().

OTT

OTTMediaOptions options = new OTTMediaOptions();
options.assetId = ASSET_ID;
options.assetType = APIDefines.KalturaAssetType.Media;
options.contextType = APIDefines.PlaybackContextType.Playback;
options.assetReferenceType = APIDefines.AssetReferenceType.Media;
options.protocol = PhoenixMediaProvider.HttpProtocol.Https;
options.startPosition = START_POSITION;

Note that above, most of the properties are optional. The values that should be passed are application- and service- dependant.

OVP

OVPMediaOptions options = new OVPMediaOptions();
options.entryId = ENTRY_ID;
options.startPosition = START_POSITION;

Depending on account setup, it’s possible that a per-entry-KS is required. The KS can be set on the options object.

Common

Send to player:

player.loadMedia(ottMediaOptions) { mediaOptions, entry, loadError ->
    if (loadError != null) {
        Snackbar.make(findViewById(android.R.id.content), loadError.getMessage(), Snackbar.LENGTH_LONG).show();
    } else {
        log.d("OTTMedia onEntryLoadComplete entry = " + entry.getId());
    }
}

The application doesn’t need to call player.prepare() and/or player.play() from the callback. This is (optionally) done automatically by the player, depending on the values of autoPlay and preload init options.

Basic Player

In this setup, the media providers are skipped. This is relevant in custom setups and when Kaltura backend is not used.

The application creates a PKMediaSource object with a list of PKMediaSources, like in PlayKit. It then passes the object to player.setMedia().

Network Performance Optimizations

Warmup Connections

It’s possible to pre-connect to servers and keep the connection up (keep-alive), so that when the player needs to start playing the connection time is reduced.

The application should determine the host names it uses, and call PKHttpClientManager.warmUp(…) with a list of URLs. In the list, there should only be one URL per host. It should request a static file that is normally cached by the CDN. In most cases, favicon.ico or crossdomain.xml should work:

PKHttpClientManager.warmUp (
      "https://cdnapisec.kaltura.com/favicon.ico",
      "https://cfvod.kaltura.com/favicon.ico"
      "https://rest-us.ott.kaltura.com/crossdomain.xml",
      );

In the above example, is the main entry-point to Kaltura's SaaS API, is the CloudFront CDN gateway, and is one of the OTT REST servers.

Only list the required services – for example, OVP apps should not connect to the OTT gateway, and apps that don’t use CloudFront as CDN should not connect to .

Plugins

Plugin configuration in Kaltura Player is very similar to PlayKit, with two primary differences:

  1. The PKPluginConfigs object is now a property of PlayerInitOptions
  2. For plugins that are published by Kaltura, there’s no need to call PlayKitManager.registerPlugins() – because these plugins are known to Kaltura Player, it takes care of registering them.

Kava (Kaltura Analytics)

Kava Analytics is being handled internally but if the app needs to pass additional params to Kava like referrer, customVar1, customVar2 etc, it needs to use the following:

//Set your configurations.
KavaAnalyticsConfig kavaConfig = new KavaAnalyticsConfig()
        .setPartnerId(123456) //Your partnerId. Mandatory field!
        .setBaseUrl("yourBaseUrl")
        .setUiConfId(123456)
        .setKs("your_ks")
        .setPlaybackContext("yourPlaybackContext")
        .setReferrer("your_referrer")
        .setDvrThreshold(1000) //Threshold from the live edge.
        .setCustomVar1("customVar1")
        .setCustomVar2("customVar2")
        .setCustomVar3("customVar3");

//Set Kava configurations to the PKPluginConfig.
pluginConfigs.setPluginConfig(KavaAnalyticsPlugin.factory.getName(), kavaConfig);

Then this PKPluginConfigs object can be passed in

playerInitOptions.setPluginConfigs(pluginConfigs);

IMA

Add to build.gradle:

implementation 'com.kaltura.playkit:imaplugin:4.0.0'

Create IMAConfig, set properties, and add to PKPluginConfigs:

IMAConfig imaAdsConfig = new IMAConfig();
// TODO: configure IMA plugin here
// Add to pluginConfigs
pluginConfigs.setPluginConfig(IMAPlugin.factory.getName(), imaAdsConfig);

### Youbora

Add to build.gradle:

    implementation 'com.kaltura.playkit:youboraplugin:4.0.0'

Create a `JsonObject`, set properties, and add to `PKPluginConfigs`:

JsonObject youboraConfig = new JsonObject();
// TODO: configure Youbora plugin here
// Add to pluginConfigs
pluginConfigs.setPluginConfig(YouboraPlugin.factory.getName(), youboraConfig);

VR and Cast

VR and Cast are not managed as plugins:

As such, their only relevance is build.gradle dependencies:

// VR Plugin
implementation 'com.kaltura.playkit:vrplugin:4.0.0'

// Google Cast
implementation 'com.kaltura.playkit:googlecast:4.0.0'

Other Plugins

Plugins that are not published by Kaltura are not known to the player. The app configures them just like it does with IMA and Youbora - the only difference is that it needs to first call PlayKitManager.registerPlugins().

Player Settings

Auto play and Preload

If the app has disabled preload, it has to call player.prepare() to start loading media, normally after the callback from loadMedia() was called. If autoplay is disabled, the player will not start playing immediately when ready, and the app will have to call player.play().

Audio and Captions/subtitles

Other