Player configuration

Some of the most impactful PlayerConfiguration options live on their own pages: Analytics, Advertising, and Thumbnails. This page covers the rest: fine-tuning buffering and retry behavior, and autoplay. For the essentials — loading content, supported formats, start time, and volume — see Player basics. For language preferences, see Tracks and languages.

Streaming configuration

The StreamingConfiguration object lets you fine-tune buffering and segment download behavior. Pass it under the streaming key:

player.open({
  source: 'https://example.com/manifest.mpd',
  streaming: {
    bufferingGoal: 20,  // seconds to buffer ahead of the playhead (default: 10)
    rebufferingGoal: 5, // minimum seconds to resume after a stall; must be <= bufferingGoal (default: 2)
    bufferBehind: 30,   // seconds of content kept behind the playhead (default: 30)
  },
});

Retry configuration

The player retries failed network requests automatically. Control retry behavior through AttemptParameters:

• streaming.attemptParameters controls retries for segment requests.

• manifest.attemptParameters controls retries for manifest requests.

player.open({
  source: 'https://example.com/manifest.mpd',
  streaming: {
    attemptParameters: {
      maxAttempts: 5,    // maximum number of attempts (including the first)
      baseDelay: 1000,   // delay before the first retry, in milliseconds
      backoffFactor: 2,  // multiplier applied to the delay on each retry
      fuzzFactor: 0.5,   // randomization factor to spread retry timing
      timeout: 30000,    // per-request timeout in milliseconds; 0 = unlimited
    },
  },
  manifest: {
    attemptParameters: {
      maxAttempts: 3,
      baseDelay: 500,
      backoffFactor: 2,
      fuzzFactor: 0.5,
      timeout: 15000,
    },
  },
});

Low latency

For low latency streaming configuration, see Low latency.

Autoplay

The autoplay option controls whether playback starts immediately after Player.open resolves. Without it, content loads and buffers but stays paused.

await player.open({
  source: '//example.com/manifest1.mpd',
  autoplay: false, // default
});

// Content is ready but paused — start playback after the button is clicked
playButton.addEventListener('click', () => player.play());

With autoplay: true, the player starts playing as soon as the content is ready, with no additional call:

await player.open({
  source: '//example.com/manifest1.mpd',
  autoplay: true,
});
// Playback starts automatically when load() resolves

Use the autoplay configuration option rather than the HTML <video autoplay> attribute. The player ignores the HTML attribute to avoid conflicts with its own autoplay implementation.

Review the browser autoplay policy below before configuring autoplay.

Browser autoplay policy

Modern browsers restrict autoplay of media with audio. The MDN autoplay guide covers the full policy — the key points:

• Autoplay with sound requires prior user interaction with the page (click, tap, or key press).

• Muted video autoplay is generally allowed without prior interaction.

This policy applies to all programmatic attempts to start playback, not just the autoplay option. Calling Player.play from a script — for example on page load — is subject to the same restrictions. Only calls triggered directly by a user gesture (click, tap, or key press) are guaranteed to succeed.

To play a video immediately on page load, it must start out muted.

// Playback starts immediately and muted
await player.open({
  source: '//example.com/manifest1.mpd',
  autoplay: true,
  muted: true,
});

// The user can enable audio later by clicking a button
muteButton.addEventListener('click', () => {
  player.setMuted(false);
});

If the browser blocks autoplay, Player.open rejects with an error (the same applies to Player.play).

Next topic: Player surface

Previous topic: Player basics