Docs | Android

Player Settings

The Player has settings object that can be configured for player instance

   interface Settings {
        /**
         * Set the Player's contentRequestAdapter.
         *
         * @param contentRequestAdapter - request adapter.
         * @return - Player Settings.
         */
        Settings setContentRequestAdapter(PKRequestParams.Adapter contentRequestAdapter);

        /**
         * Set the Player's licenseRequestAdapter.
         *
         * @param licenseRequestAdapter - request adapter.
         * @return - Player Settings.
         */
        Settings setLicenseRequestAdapter(PKRequestParams.Adapter licenseRequestAdapter);

        /**
         * Enable/disable cea-608 text tracks.
         * By default they are disabled.
         * Note! Once set, this value will be applied to all mediaSources for that instance of Player.
         * In order to disable/enable it again, you should update that value once again.
         * Otherwise it will stay in the previous state.
         *
         * @param cea608CaptionsEnabled - should cea-608 track should be enabled.
         * @return - Player Settings.
         */
        Settings setCea608CaptionsEnabled(boolean cea608CaptionsEnabled);

        /**
         * Enable/disable MPGA audio tracks.
         * By default they are disabled.
         * Note! Once set, this value will be applied to all mediaSources for that instance of Player.
         * In order to disable/enable it again, you should update that value once again.
         * Otherwise it will stay in the previous state.
         *
         * @param mpgaAudioFormatEnabled - should Enable MPGA Audio track.
         * @return - Player Settings.
         */
        Settings setMpgaAudioFormatEnabled(boolean mpgaAudioFormatEnabled);

        /**
         * Decide if player should use {@link android.view.TextureView} as primary surface
         * to render the video content. If set to false, will use the {@link android.view.SurfaceView} instead.
         * Note!!! Use this carefully, because {@link android.view.TextureView} is more expensive and not DRM
         * protected. But it allows dynamic animations/scaling e.t.c on the player. By default it will be always set
         * to false.
         *
         * @param useTextureView - true if should use {@link android.view.TextureView}.
         * @return - Player Settings.
         */
        Settings useTextureView(boolean useTextureView);

        /**
         * Decide if player should do cross protocol redirect or not. By default it will be always set
         * to false.
         *
         * @param crossProtocolRedirectEnabled - true if should do cross protocol redirect.
         * @return - Player Settings.
         */
        Settings setAllowCrossProtocolRedirect(boolean crossProtocolRedirectEnabled);

        /**
         * Decide if player should play clear lead content
         *
         * @param allowClearLead - should enable/disable clear lead playback default true (enabled)
         * @return - Player Settings.
         */
        Settings allowClearLead(boolean allowClearLead);

        /**
         * Decide whether to enable fallback to lower-priority decoders if decoder initialization fails
         *
         * @param enableDecoderFallback - should enable/disable enableDecoderFallback default true (enabled)
         * @return - Player Settings.
         */
        Settings enableDecoderFallback(boolean enableDecoderFallback);
        /**
         * Decide if player should use secure rendering on the surface.
         * Known limitation - when useTextureView set to true and isSurfaceSecured set to true -
         * secure rendering will have no effect.
         *
         * @param isSurfaceSecured - should enable/disable secure rendering
         * @return - Player Settings.
         */
        Settings setSecureSurface(boolean isSurfaceSecured);

        /**
         * Decide the Ad will be auto played when comes to foreground from background
         *
         * @param autoPlayOnResume true if it is autoplayed or else false, default is TRUE
         * @return Player Settings
         */
        Settings setAdAutoPlayOnResume(boolean autoPlayOnResume);

        /**
         * Set the player buffers size
         *
         * @param loadControlBuffers LoadControlBuffers
         * @return Player Settings
         */
        Settings setPlayerBuffers(LoadControlBuffers loadControlBuffers);

        /**
         * Set the Player's VR/360 support
         *
         * @param vrPlayerEnabled - If 360 media should be played on VR player or default player - default == true.
         * @return - Player Settings.
         */
        Settings setVRPlayerEnabled(boolean vrPlayerEnabled);

        /**
         * Set the Player's preferredAudioTrackConfig.
         *
         * @param preferredAudioTrackConfig - AudioTrackConfig.
         * @return - Player Settings.
         */
        Settings setPreferredAudioTrack(PKTrackConfig preferredAudioTrackConfig);

        /**
         * Set the Player's preferredTextTrackConfig.
         *
         * @param preferredTextTrackConfig - TextTrackConfig.
         * @return - Player Settings.
         */
        Settings setPreferredTextTrack(PKTrackConfig preferredTextTrackConfig);

        /**
         * Set the Player's PreferredMediaFormat.
         *
         * @param preferredMediaFormat - PKMediaFormat.
         * @return - Player Settings.
         */
        Settings setPreferredMediaFormat(PKMediaFormat preferredMediaFormat);

        /**
         * Set the Player's Subtitles
         *
         * @param subtitleStyleSettings - SubtitleStyleSettings
         * @return - Player Settings
         */
        Settings setSubtitleStyle(SubtitleStyleSettings subtitleStyleSettings);

        /**
         *  Set the Player's ABR settings
         *
         * @param abrSettings ABR settings
         * @return - Player Settings
         */
        Settings setABRSettings(ABRSettings abrSettings);

        /**
         *  Set the Player's AspectRatio resize Mode
         *
         * @param resizeMode Resize mode
         * @return - Player Settings
         */
        Settings setSurfaceAspectRatioResizeMode(PKAspectRatioResizeMode resizeMode);

        /**
         * Do not prepare the content player when the Ad starts(if exists); instead content player will be prepared
         * when content_resume_requested is called.
         *
         * Default value is set to 'false'.
         *
         * @param forceSinglePlayerEngine Do not prepare the content player while Ad is playing
         * @return - Player Settings
         */
        Settings forceSinglePlayerEngine(boolean forceSinglePlayerEngine);
      
        /**
         * Set the flag which handles the video view
         * @param hide video surface visibility
         */
        Settings setHideVideoViews(boolean hide);

        /**
         * Set VR Settings on the player
         * @param vrSettings vr configuration
         */
        Settings setVRSettings(VRSettings vrSettings);
    }
    }  

Once you created a player instance you can set the above settings on it.

Example

Create a player:

 Player player = PlayKitManager.loadPlayer(context, pluginConfigs);

Apply Player Settings if required:

Enable crossProtocolRedirect

Example:

 //Configure if to player allow http/https mix.
 player.getSettings().setAllowCrossProtocolRedirect(crossProtocolRedirectEnabled); // default is false

Enable DRM Clear Lead Playback

Example:

 //Configure if player will start playing clear lead in DRM content 
 player.getSettings(). allowClearLead(true/false); // default is false

Enable Secure Surface

In case App wants to block ability to take screen capture

Example:

 player.getSettings().setSecureSurface(isSurfaceSecured); // default is false

Configure Player’s PreferredMediaFormat.

By default if MediaEntry contains multiple sources from different formats player will choose DASH (mpd) and if this format isavailable it will try to select hls and so on. in orer to force some other thay over the default formats priority use the following API with one of :

  player.getSettings().setPreferredMediaFormat(PKMediaFormat.dash);
  player.getSettings().setPreferredMediaFormat(PKMediaFormat.hls);
  player.getSettings().setPreferredMediaFormat(PKMediaFormat.wvm);
  player.getSettings().setPreferredMediaFormat(PKMediaFormat.mp4);
  player.getSettings().setPreferredMediaFormat(PKMediaFormat.mp3);

Configure Player Load Control

Using builder api you can create LoadControl Buffers with the default ExoPlayer values then it is possible configure any parameter from the LoadControlBuffers Object.

Defaults can be found here: Defaults

Example:

             LoadControlBuffers loadControlBuffers = new LoadControlBuffers().
                    setMinPlayerBufferMs(2000).
                    setMaxPlayerBufferMs(45000).
                    setBackBufferDurationMs(2000).
                    setMinBufferAfterReBufferMs(2000).
                    setMinBufferAfterInteractionMs(2000).
                    setRetainBackBufferFromKeyframe(true);
                    
            player.getSettings().setPlayerBuffers(loadControlBuffers);

Configure if to use TextureView instead of surface view

Example:

 player.getSettings().useTextureView(false); // default is false

Enable Cea608Captions

Example:

 //Configure if to consider Cea608Captions which exist stream for text track selection.
 player.getSettings().setCea608CaptionsEnabled(false); // default is false

Configure KalturaPlaybackRequestAdapter

Example:

//Configure different app name/domain in KalturaPlaybackRequestAdapter which allows adapting the request parameters before sending network requests

 KalturaPlaybackRequestAdapter.install(player, "your access control domain"); // default is app package name

Note: the domain must have both Scheme like https:// or app:// and Authority. Ex. “app://test.domain.com” where app:// is the schema and test.domain.com is the Authority

Configure KalturaUDRMLicenseRequestAdapter

Example:

//configure different app name/domain in KalturaUDRMLicenseRequestAdapter which allows adapting the request parameters before sending DRM requests
 
KalturaUDRMLicenseRequestAdapter.install(player, "your access control domain"); // default is app package name

Note: the domain must have both Scheme like https:// or app:// and Authority. Ex. “app://test.domain.com” where app:// is the schema and test.domain.com is the Authority

Enable - Ad will auto play on resume

In some cases where app does not expose play pause api on ads this api will do the auto play after resume from background

Example:

player.getSettings().setAdAutoPlayOnResume(autoPlayOnResume);

setVRPlayerEnabled(boolean vrPlayerEnabled);

If case 360 media should be played on VR player or default player - default is true

Example:

player.getSettings().setVRPlayerEnabled(vrPlayerEnabled);

Configure preferred TEXT TRACKS – Default is no captions displayed.

Example:

 //player.getSettings().setPreferredTextTrack(new PKTrackConfig().setPreferredMode(PKTrackConfig.Mode.OFF)); // no text tracks
 //player.getSettings().setPreferredTextTrack(new PKTrackConfig().setPreferredMode(PKTrackConfig.Mode.SELECTION).setTrackLanguage("hi")); // select specific track lang if not exist select manifest default if exist else the first from manifest
 player.getSettings().setPreferredTextTrack(new PKTrackConfig().setPreferredMode(PKTrackConfig.Mode.AUTO)); // select the track by locale if does not exist manifest default

 /Configure preferred AUDIO TRACKS - Default is Stream's default

 //player.getSettings().setPreferredAudioTrack(new PKTrackConfig().setPreferredMode(PKTrackConfig.Mode.OFF); // default audio track (Done automatically actually)
 //player.getSettings().setPreferredAudioTrack(new PKTrackConfig().setPreferredMode(PKTrackConfig.Mode.SELECTION).setTrackLanguage("ru")); // select specific track lang if not exist select manifest default
 player.getSettings().setPreferredAudioTrack(new PKTrackConfig().setPreferredMode(PKTrackConfig.Mode.AUTO));

Set Preferred Audio/Text Track

In order to configure this behaviour you have to instantiate PKTrackConfig This object can be created via builder methods inorder to add a audio/text tracks preffered Config Mode/Language. using:

 public PKTrackConfig setTrackLanguage(String trackLanguage)
 public PKTrackConfig setPreferredMode(@NonNull Mode preferredMode)

Example

 PKTrackConfig trackConfig = new PKTrackConfig().setPreferredMode(PKTrackConfig.Mode.OFF);
 PKTrackConfig trackConfig = new PKTrackConfig().setPreferredMode(PKTrackConfig.Mode.AUTO);
 PKTrackConfig trackConfig = new  PKTrackConfig().setPreferredMode(PKTrackConfig.Mode.SELECTION).setTrackLanguage("ru")

Once we have the PKTrackConfig object we can use it as parameter for the api.

player.getSettings().setPreferredAudioTrack(preferredAudioTrackConfig)
player.getSettings().setPreferredTextTrack(preferredTextTrackConfig)

Tracks Configuration possibilities

There are 3 modes available:

• OFF - for Text tracks it will cancel text tracks display for audio it will select the default from the manifest
• AUTO - SDK will check if the stream has audio/text track that matches the device locale and will select it else it will take stream default
• SELECTION - this mode requires to set the language explicitly (2 or 3 letters) if this language does not exist SDK will take the streams default Audio/Text track

NOTE!!!

The languages that are expected by player should match the SO 639-X codes definition

Subtitle Sideloading for Player

Since Playkit version 3.9.0

To load Subtitle from external source for the player, need to create a List of PKExternalSubtitle and then pass it to PKMediaEntry object.

PKExternalSubtitle pkExternalSubtitle = new PKExternalSubtitle()
                .setUrl("http://URL_OF_EXTERNAL_SUBTITLE.vtt")
                .setMimeType(PKSubtitleFormat.vtt)
                .setLabel("de")
                .setLanguage("deu");
mList.add(pkExternalSubtitle);

mediaEntry.setExternalSubtitleList(mList);

Supported MimeTypes are PKSubtitleFormat.vtt, PKSubtitleFormat.srt, PKSubtitleFormat.ttml.

Use setDefault() while creating PKExternalSubtitle to make it default subtitle.

Subtitle Styles for Player

Since Playkit version 3.7.1

To configure Subtitles to the player, first need to set the Subtitles using settings from playerobject. While creating SubtitleStyleSettings object, need to pass subtitleStyleName param in constructor.

SubtitleStyleSettings subtitleStyleSettings = new SubtitleStyleSettings("MyCustomSubtitleStyle");
player.getSettings().setSubtitleStyle(subtitleStyleSettings);

To update the Subtitles call updateSubtitleStyle() using only player object. Use updated subtitleStyleSettings object.

player.updateSubtitleStyle(subtitleStyleSettings);

Using builder pattern for setters in subtitleStyleSettings, Following Styles can be applied,

• setTextColor - Change subtitle text color
• setBackgroundColor - Change subtitle background color
• setEdgeColor - Change subtitle text edge color

• setWindowColor - Change subtitle window color

• setEdgeType - Change subtitle Edge types using enum SubtitleStyleEdgeType with the values EDGE_TYPE_NONE, EDGE_TYPE_OUTLINE, EDGE_TYPE_DROP_SHADOW, EDGE_TYPE_RAISED, EDGE_TYPE_DEPRESSED;

• setTextSizeFraction - Change subtitle text size fraction using enum SubtitleTextSizeFraction with the values SUBTITLE_FRACTION_50, SUBTITLE_FRACTION_75, SUBTITLE_FRACTION_100, SUBTITLE_FRACTION_125, SUBTITLE_FRACTION_150, SUBTITLE_FRACTION_175, SUBTITLE_FRACTION_200

• setTypeface - Change subtitle typeface using enum SubtitleStyleTypeface with the values DEFAULT, DEFAULT_BOLD, MONOSPACE, SERIF, SANS_SERIF

Example

To set the Subtitles,

SubtitleStyleSettings subtitleStyleSettings = new SubtitleStyleSettings("MyCustomSubtitleStyle")
                    .setBackgroundColor(Color.BLUE)
                    .setTextColor(Color.WHITE)
                    .setTextSizeFraction(SubtitleStyleSettings.SubtitleTextSizeFraction.SUBTITLE_FRACTION_50)
                    .setWindowColor(Color.YELLOW)
                    .setEdgeColor(Color.BLUE)
                    .setTypeface(SubtitleStyleSettings.SubtitleStyleTypeface.MONOSPACE)
                    .setEdgeType(SubtitleStyleSettings.SubtitleStyleEdgeType.EDGE_TYPE_DROP_SHADOW);

player.getSettings().setSubtitleStyle(subtitleStyleSettings);

To update the existing Subtitles,

SubtitleStyleSettings subtitleStyleSettings = new SubtitleStyleSettings("MyNewCustomSubtitleStyle")
                        .setBackgroundColor(Color.WHITE)
                        .setTextColor(Color.RED)
                        .setTextSizeFraction(SubtitleStyleSettings.SubtitleTextSizeFraction.SUBTITLE_FRACTION_100)
                        .setWindowColor(Color.BLUE)
                        .setEdgeColor(Color.BLUE)
                        .setTypeface(SubtitleStyleSettings.SubtitleStyleTypeface.SANS_SERIF)
                        .setEdgeType(SubtitleStyleSettings.SubtitleStyleEdgeType.EDGE_TYPE_DROP_SHADOW);

player.updateSubtitleStyle(subtitleStyleSettings);

Subtitle Positioning for Player

Since Playkit version 4.8.0

####API

• PKSubtitlePosition pkSubtitlePosition = PKSubtitlePosition(boolean overrideInlineCueConfig)

  If overrideInlineCueConfig is set to true then player will use the given Cue Settings to override the values coming in Cue Settings. Top (10 is for 10%) to Bottom (100 is for 100%)

• setVerticalPosition(int verticalPositionPercentage)

  Set the subtitle position only in Vertical direction (Up or Down) on the video frame. This method only allows to move in Y - coordinate.

• setPosition(int horizontalPositionPercentage, int verticalPositionPercentage, Layout.Alignment horizontalAlignment)

  Set the subtitle position any where on the video frame. This method allows to move in X-Y coordinates.

  • horizontalPositionPercentage Set the horizontal(Left/Right viewport) positions, percentage starts from center(10 is for 10%) to Left/Right(100 is for 100%)
  • verticalPositionPercentage Set the vertical(Top to Bottom) positions, percentage starts from Top(10 is for 10%) to Bottom(100 is for 100%)
  • horizontalAlignment Allow the subtitle view to move left (ALIGN_NORMAL), middle (ALIGN_CENTER) and right (ALIGN_OPPOSITE). For RTL texts, Allow the subtitle view to move Right (ALIGN_NORMAL), middle (ALIGN_CENTER) and left (ALIGN_OPPOSITE)

  Note: If horizontal alignment and horizontal position is not valid then treat it as setVerticalPosition(int verticalPositionPercentage).

• setToDefaultPosition(boolean overrideInlineCueConfig)

  If overrideInlineCueConfig is false that means; app does not want to override the inline Cue configuration. App wants to go with Cue configuration.

  BUT Beware that it will call setOverrideInlineCueConfig(boolean) with false value means after that in next call, app needs to setOverrideInlineCueConfig(boolean) with another value.

  Otherwise

  If overrideInlineCueConfig is true then it will move subtitle to Bottom-Center which is a standard position for it.

• setOverrideInlineCueConfig(boolean overrideInlineCueConfig)

  If overrideInlineCueConfig is set to true then player will use the given Subtitle postion Settings to override the values coming in Cue itself.

######Note: Horizontal / Vertical position percentage limit is between 10% to 100%.

####Example

To set the subtitle position, it is part of SubtitleStyleSettings

PKSubtitlePosition pkSubtitlePosition = new PKSubtitlePosition(`overrideInlineCueConfig` boolean);
// horizontalPositionPercentage = 70 (70%)
// verticalPositionPercentage = 30 (30%)
pkSubtitlePosition.setPosition(horizontalPositionPercentage, verticalPositionPercentage, Layout.Alignment.ALIGN_OPPOSITE);  

subtitleStyleSettings.setSubtitlePosition(pkSubtitlePosition);
player.getSettings().setSubtitleStyle(subtitleStyleSettings);

To update the subtitle position, use the new configuration and use it in the following way,

pkSubtitlePosition.setToDefaultPosition(true);

subtitleStyleSettings.setSubtitlePosition(pkSubtitlePosition);
player.updateSubtitleStyle(subtitleStyleSettings);

Configure Player Aspect Ratio

Since Playkit version 3.9.0

App can set the player aspect ratio for the following values:

public enum PKAspectRatioResizeMode {
    fit,
    fixedWidth,
    fixedHeight,
    fill,
    zoom
}

Example giving default value at start time

player.getSettings().setSurfaceAspectRatioResizeMode(PKAspectRatioResizeMode.fit);

Example giving new value at run time

player.updateSurfaceAspectRatioResizeMode(PKAspectRatioResizeMode.fill);

Example adding listener for aspect ratio changes

player.addListener(this, PlayerEvent.surfaceAspectRationSizeModeChanged, event -> {
            log.d("resizeMode updated" + event.resizeMode);
});

Configure ABR Settings

Since Playkit version 3.9.0

App can configureits min/max video bitrates that player should do ABR and video tracks selection with. In addition app can configure its preffer initial bitrate by adding setInitialBitrateEstimate to the api

Example

// --->  Min-Max video bitrate
// --->  Sets the initial bitrate estimate in bits per second that should be assumed when a bandwidth estimate is unavailable.
player.getSettings().setABRSettings(new ABRSettings().setMinVideoBitrate(250000).setMaxVideoBitrate(3000000).setInitialBitrateEstimate(100000));

Configure Hide Video View - used for Audio Only playback where som artwork should be displayed instead of video view

Since Playkit version 3.9.4

Example

player.getSettings().setHideVideoViews(true);

Configure VR Settings

Since Playkit version 4.0.0

App will configure the VR bettings on player level and not for each media

Example

if (mediaEntry.isVRMediaType()) {
    VRSettings vrSettings = new VRSettings();
    vrSettings.setFlingEnabled(true);
    vrSettings.setVrModeEnabled(false);
    vrSettings.setInteractionMode(VRInteractionMode.MotionWithTouch);
    vrSettings.setZoomWithPinchEnabled(true);
    VRInteractionMode interactionMode = vrSettings.getInteractionMode();
    if (!VRUtil.isModeSupported(MainActivity.this, interactionMode)) {
       //In case when mode is not supported we switch to supported mode.
        vrSettings.setInteractionMode(VRInteractionMode.Touch);
    }
    player.getSettings().setVRSettings(vrSettings);
}    

Configure Force Single player instance playback

Since Playkit version 4.0.0

for Ad Playback on Low End devices with single video decoder

Example

player.getSettings().forceSinglePlayerEngine(true);

Configure enableDecoderFallback

Since Playkit version 4.0.1

Whether to enable fallback to lower-priority decoders if decoder initialization fails default is false

Example

player.getSettings().enableDecoderFallback(true);