About

Playback settings control how media plays in the Kaltura player, such as whether it starts automatically, which caption and audio languages it uses, and whether it starts loading before the viewer selects play.

You can configure playback in two places:

• Player Studio in the Rich Media Content Management System (Rich Media CMS): Use it to set the default playback behavior for every embed of a player.
• The JavaScript embed configuration (config.playback): Use it to override playback behavior at runtime, for example to set the language from the user's profile, turn on autoplay on specific pages, or disable the user cache for exams.

In the player configuration object, playback options go in the playback parameter, which is of type PKPlaybackConfigObject. This is its structure.

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,
    screenLockOrientationMode: string
  },
  ...
};

---

Default values

These are the default values for config.playback.

{
  audioLanguage: "",
  textLanguage: "",
  volume: 1,
  playsinline: true,
  preload: "none",
  autoplay: false,
  loop: false,
  allowMutedAutoPlay: true,
  muted: false,
  pictureInPicture: true,
  playAdsWithMSE: false,
  screenLockOrientationMode: 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 covers parameters that are often configured for playback:

• Disable user preferences
• Captions default display
• Default audio language
• Closed captioning (CC) button
• Preload media
• Autoplay
• Fallback to muted autoplay
• Start playback muted
• Autopause
• Screen lock orientation
• Support YouTube playback

---

Disable user preferences (config.disableUserCache)

By default, the player remembers changes the viewer makes, such as volume, muted state, playback speed, audio track, and captions. It saves them in the browser's localStorage and restores them on later visits.

To turn this off, set disableUserCache to true at the root level of your player configuration, not under playback. For example, you might do this in assessment or testing environments, where every viewer must start with the default volume and normal speed.

Type: boolean

Default value: false

Possible values:

• false: The player saves preferences in localStorage across sessions.
• true: The player doesn't use the cache, and always starts with the defaults from the initial configuration.

This example turns off user preferences.

const config = {
  targetId: 'player-placeholder',
  provider: { partnerId: 123456 },
  disableUserCache: true // Disables remembering user volume, speed, etc.
};

---

Captions default display (config.playback.textLanguage)

Captions can show by default when the viewer starts playback. You can start without captions, show captions in a specific language if they're available, or let the player choose the language automatically.

Type: string

Default value: ""

Possible values:

• "off": Start playback without captions.
• "<language>": Start playback with captions in the specified language, if available.

• "auto": Start playback with captions in a language the player selects automatically.

---

Default audio language (config.playback.audioLanguage)

Sets which audio track plays by default when playback starts. You can use an audio track in a specific language if it's available, or let the player choose the language automatically.

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 viewer's system locale, if an audio track in that language is available.

---

Closed captioning (CC) button (config.ui.showCCButton)

Sets whether the player shows a closed captioning (CC) button over the video, as part of the player UI. Viewers select the button to turn captions on or off.

Type: boolean

Default value: false

Possible values:

• true: Show the CC button.
• false: Don't show the CC button.

---

Preload media (config.playback.preload)

When your front-end app loads and sets up the player, you can start loading the media right away, before the viewer selects play. Preloading can shorten the time it takes playback to start. It can also add costs, for example if your media files are licensed or charged per view, or for extra bandwidth.

Type: string

Default value: "none"

Possible values:

• "none": The media doesn't preload. It starts loading when the viewer starts playback.
• "metadata": Only the media metadata (duration, dimensions, and tracks) preloads.
• "auto": The player starts buffering media segments as soon as it loads.

---

Autoplay (config.playback.autoplay)

When the player loads, the media can start playing automatically.

Some browsers, such as Safari and Google Chrome, block autoplay, so the media doesn't start playing. If allowMutedAutoPlay is turned on, the media still autoplays in these browsers, but without sound. For more information, see Fallback to muted autoplay, below.

Type: boolean or string

Default value: false

Possible values:

• false: Autoplay is turned off.
• "inview": Playback starts automatically, but only when the player first comes into view.
• true: Playback starts automatically when the media loads.

---

Fallback to muted autoplay (config.playback.allowMutedAutoPlay)

If the browser doesn't allow media to autoplay with audio, the player can autoplay it without audio instead. The viewer then needs to unmute the player.

Type: boolean

Default value: true

Possible values:

• false: If the browser blocks autoplay, the media doesn't autoplay. The viewer needs to start playback.
• true: If the browser blocks autoplay, the media still autoplays, but without audio.

---

Start playback muted (config.playback.muted)

Sets whether media starts with or without audio.

Type: boolean

Default value: false

Possible values:

• false: Playback starts with audio.
• true: Playback starts without audio.

---

Autopause (config.playback.autopause)

Sets whether playback pauses automatically when the player isn't in view.

Type: boolean

Default value: false

Possible values:

• false: Playback continues when the player isn't in view.
• true: Playback pauses automatically when the player isn't in view.

---

Screen lock orientation (config.playback.screenLockOrientationMode)

Sets the default screen orientation when the screen is locked and the player enters full screen mode.

Type: string

Default value: none

Possible values:

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

For more information, see Screen lock orientation in the MDN Web Docs.

---

Support YouTube playback (config.playback.streamPriority)

Lets the player get and play video content from YouTube's back end.

The parameter is of type streamPriority. This is its structure.

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 Widevine DRM-protected content.