Playback Configuration

Introduction

Playback options can be configured in The Kaltura Player Studio in the Kaltura Management Console (KMC) or in the front-end application. 

Within the configuration object provided to the Player, you can configure various options related to playback (eg., if the media file starts loading before the user selects it or if playback will begin automatically, etc.). This is done via the playback parameter within the configuration object.

The input for the "playback" parameter is of type PKPlaybackConfigObject, which is structured as follows:

var config = {
    ...
    playback: {
        {
            audioLanguage: string,
            textLanguage: string,
            volume: number,
            playsinline: boolean,
            crossOrigin: string,
            preload: string,
            autoplay: PKAutoPlayTypes,
            loop: boolean,
            autopause: boolean,
            allowMutedAutoPlay: boolean,
            muted: boolean,
            pictureInPicture: boolean,
            options: PKPlaybackOptionsObject,
            streamPriority: Array < PKStreamPriorityObject > ,
            preferNative: PKPreferNativeConfigObject,
            inBrowserFullscreen: boolean,
            playAdsWithMSE: boolean,
            screenLockOrientionMode: string
        }    },
     ...
};

Default values

Default values for config.playback are as follows:

{ 
audioLanguage: "", 
textLanguage: "", 
volume: 1, 
playsinline: true, 
preload: "none", 
autoplay: false, 
loop: false, 
allowMutedAutoPlay: true, 
muted: false, 
pictureInPicture: true, 
playAdsWithMSE: false, 
screenLockOrientionMode: ScreenOrientationType.NONE, 
options: {
   html5: {
     hls: {},
     dash: {}
   }
 },
 preferNative: {
   hls: false,
   dash: false
 },
 streamPriority: [
   {
     engine: "html5",
     format: "hls"
   },
   {
     engine: "html5",
     format: "dash"
   },
   {
     engine: "html5",
     format: "progressive"
   }
 ]
}

Common Configurations

This section contains several commonly-configured parameters related to playback:

• Apply User Preferences
• Captions Default Display
• Default Audio Language
• Closed Captioning (CC) Button
• Preload
• Autoplay
• Fallback to Muted Autoplay
• Autopause
• Start Playback Muted
• Screen Lock Orientation
• Support YouTube Playback

Apply User Preferences (Name of Param/type/values)

Saves the user's modifications in the browser's cache and automatically applies them when a new Player instance is created. All settings that the user modifies - e.g. volume, audio language, text language, or playback speed - remain modified the next time the user starts playback. For example, if the user selects Mute Player, then the next time that the Player is loaded it will start playback with the volume off.

Clearing the cache or entering incognito mode returns settings to default values.

The user preference feature works on all browsers that support the localStorage option.

Type: Boolean

Default value: false

Possible values: 

• "true" – Do not use browser cache

• "false" –  Use browser cache

Captions Default Display (config.playback.textLanguage)

Captions can be displayed by default when a user begins playback. There are several possible configurations: (1) do not display captions initially; (2) display captions in a specified language (if captions in that language are available); (3) display captions in an automatically-selected language.

See notes about limitations in  "Possible values" section, below.

Type: string

Default value: ""

Possible values:

• "off" – Start playback without captions
• "<language>" – Start playback with captions displaying in the specified language (if available).

• "auto" – Start playback with captions displaying in an automatically-selected language. 

Default Audio Language (config.playback.audioLanguage)

Defines which audio track will be used by default when playback starts. There are several possible configurations: (1) use audio track in a specified language (if an audio track in that language is available); (2) use audio track in an automatically-selected language.

See notes about limitations in the "Possible values" section, below.

Type: string

Default value:""

Possible values:

• "<language>" – Start playback with audio in the specified language (if available). 

• "auto" - Start playback with audio in the language of the locale of the user's system (if there is an available audio track in that language)

Closed Captioning (CC) Button (config.ui.showCCButton)

Determines whether a clickable closed captioning (CC) button will be displayed over the video as part of the Player UI. This button can be clicked by the user to turn captions on or off.

Type: Boolean

Default value: false

Possible values:

• "true" – Show CC button

• "false" – Do not show CC button

Preload Media (config.playback.preload)

When the Player is instantiated and configured by the front-end application, it is possible to immediately start preloading the media content (i.e. loading it before the user selects it). Preloading media enables a better user experience as the content will start immediately; however, it can be expensive if the content files must be purchased.

Type: string

Default value: "none"

Possible values:

• "none" - The video will not be preloaded
• "auto" - The whole video file could be downloaded, even if the user is not expected to use it.

Autoplay (config.playback.autoplay)

When the Player is loaded, the media content can be set to start playing automatically by default. 

There are three possible configurations: 

1. Always start autoplaying media; 
2. Start playing media when the Player is in view on the screen; 
3. Do not autoplay media. 

Some browsers (e.g. Safari and Google Chrome) block autoplay, in which case the media content does not start autoplaying. However, if allowMutedAutoPlay is enabled, the media content WILL start autoplaying without sound (see section 3.7 Fallback to Muted Autoplay, below). 

Type: Boolean | string

Default value: false

Possible values:

• "false" -  Autoplay is turned off
• "inview"  - Playback will start automatically, but only when the Player first comes into view
• "true" - Playback will start automatically once media content is loaded

Fallback to Muted Autoplay (config.playback.allowMutedAutoPlay)

In cases where the browser does not allow autoplaying media with audio, the Player can instead autoplay media without audio. User interaction is then required to unmute the Player. 

Type: Boolean

Default value: true

Possible values:

• "false" - Media content is not autoplayed when autoplay is blocked in the runtime browser. User action will be required to start the playback.
• "true" - When autoplay is blocked in the runtime browser, media content is still autoplayed, but without audio.

Start Playback Muted (config.playback.muted)

Defines whether a video will start with or without audio by default.

Type: Boolean

Default value: false

Possible values:

• "false" - Playback will start with audio
• "true" - Playback will start without audio 

Autopause (config.playback.autopause)

Defines whether the playback should be automatically paused when the Player is not in view.  

Type: boolean

Default value: false

Possible values:

• "false" - Playback will continue when the Player is not in view
• "true" - Playback will be automatically paused when the Player is not in view

Screen Lock Orientation (config.playback.screenLockOrientationMode)

Defines the default screen orientation when the screen is locked and full screen screen mode is entered. 

Type: string

Default value: none 

Possible values: 

• none
• any
• natural 
• landscape 
• portrait 
• portrait primary
• portrait secondary
• landscape primary
• landscape secondary

For more details, see Screen Lock Orientation.

Support YouTube Playback (config.playback.streamPriority)

Allows the Player to retrieve and play video content from YouTube's back-end. 

The parameter is of type streamPriority, which is structured as follows:

streamPriority: [
   {
     engine: "youtube",
     format: "progressive"
   },
   {
     engine: "html5",
     format: "hls"
   },
   {
     engine: "html5",
     format: "dash"
   },
   {
     engine: "html5",
     format: "progressive"
   }
 ]

Type: Array <PKStreamPriorityObject>

Default value: 

• "hls" - For clear content 
• "dash" - For DRM Widevine protected