Autoplay

For the best chance of autoplay succeeding, start playback muted and enable inline playback. Autoplay is a request, not a guarantee: browsers can block it based on audio state, prior interaction with your site, browser settings, and platform policy.

Recommended approach

Set autoplay, muted, and inline playback on the media component, and keep a manual play control available for when autoplay is blocked.

<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline></video>
    <media-play-button class="media-play-button">
      <span class="paused">Play</span>
      <span class="playing">Pause</span>
      <span class="ended">Replay</span>
    </media-play-button>
  </media-container>
</video-player>

.video-player {
  position: relative;
}

.video-player video {
  width: 100%;
  aspect-ratio: 16 / 9;
}

.media-play-button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.media-play-button .paused {
  display: none;
}
.media-play-button .playing {
  display: none;
}
.media-play-button .ended {
  display: none;
}
.media-play-button[data-paused]:not([data-ended]) .paused {
  display: inline;
}
.media-play-button:not([data-paused]) .playing {
  display: inline;
}
.media-play-button[data-ended] .ended {
  display: inline;
}
.media-play-button[data-ended] .paused {
  display: none;
}
.media-play-button[data-ended] .playing {
  display: none;
}

import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/play-button';

How it works

The playback feature reflects the result in player state. When autoplay succeeds, paused becomes false and started becomes true. When the browser blocks autoplay, the player stays paused: true with started: false, and the Play button renders its play state. There is no separate autoplay failure event: a blocked autoplay looks like media that never started.

Calling play() from player state returns the native promise from the media element. When the browser blocks playback, that promise rejects with a NotAllowedError.

Availability and constraints

Common variations

Background video

These components default to muted, looping playback without player controls. Provide a separate motion control and respect reduced-motion preferences. For setup and motion controls, follow Add a background video. That guide also covers streaming backgrounds, which always autoplay and need conditional mounting.

Autoplay with sound

Do not rely on unmuted autoplay for a user’s first visit. Start playback from an explicit user action instead.

<video-player>
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsinline></video>
  </media-container>
</video-player>
<button type="button" id="start">Play video</button>
<script type="module">
  import '@videojs/html/video/player';
  import '@videojs/html/ui/container';

  document.querySelector('#start').addEventListener('click', () => {
    document.querySelector('video').play().catch(console.error);
  });
</script>

Calling play() directly from the click handler lets the browser authorize unmuted playback. The promise can still reject; these examples log the rejection and leave the button available to retry. For source and decoding failures, see Handle playback errors.

Troubleshooting

Playback does not start

Confirm that:

• The media is muted.
• Inline playback is enabled.
• The source loads (check the network panel).
• A manual play control is available as a fallback.

If autoplay is blocked, the player stays paused and the Play button remains in its play state; there is no error state to handle.

The video opens fullscreen on iPhone

The video starts without sound

Expected with muted autoplay. Give the user a Mute button to unmute through an explicit action. Unmuting without a user action can cause the browser to pause or block playback. A Volume slider can also unmute where volume control is supported; it hides on platforms such as iOS Safari.

Related pages