Why won’t my background video autoplay?

Usually because it isn’t muted. Browsers autoplay video only without sound, and iPhones also need playsinline to play it inside the page. Keep autoplay, add muted and playsinline, and make sure the poster works for the times autoplay is blocked anyway.

Should I embed the video from YouTube or Vimeo?

Not for a background. An embedded player brings its own scripts and controls, and you lose control of the poster and the fallbacks. Serve a plain MP4 from your own site or CDN.

H.264 MP4 plays in every current browser, so always have one. You can add a WebM before it, which is often smaller; browsers that can’t play it fall through to the MP4.

How to add a video background hero with Claude Code

Claude Code writes the markup for a video hero in one go. Most of the work is elsewhere: a file small enough to load on a phone, text that stays readable over every frame, and something sensible for visitors whose browser won’t play the video or who have asked for less motion.

What you need

A clip of 5 to 15 seconds with steady camera movement and a calm area where the headline will sit
FFmpeg on your PATH (brew install ffmpeg, winget install ffmpeg or apt install ffmpeg)
Claude Code, started in your site’s repository

Step 1: prepare the video file

Encode an H.264 MP4 without sound. Browsers only autoplay muted video, so an audio track is weight nobody hears.

Terminal

ffmpeg -i source.mov -t 10 -vf "scale=1920:-2,fps=30" \
  -c:v libx264 -crf 26 -preset slow -pix_fmt yuv420p \
  -an -movflags +faststart public/hero.mp4

-t 10 keeps the first ten seconds. Add -ss 4 before -i to start further in.
-crf 26 sets the quality: higher numbers make smaller, softer files. Try 23 to 30.
-pix_fmt yuv420p keeps the file playable in Safari and on phones.
-an drops the sound, and +faststart lets playback begin before the whole file has arrived.

Make a lighter copy for phones, and save the first frame as the poster that shows while the video loads:

Terminal

ffmpeg -i public/hero.mp4 -vf "scale=1280:-2" -c:v libx264 -crf 28 \
  -preset slow -pix_fmt yuv420p -an -movflags +faststart public/hero-sm.mp4
ffmpeg -i public/hero.mp4 -frames:v 1 -q:v 3 public/hero-poster.jpg

Step 2: ask Claude Code for the section

Name the files, the attributes and the fallbacks in the prompt, so the first version is close:

Claude Code

Add a full-width hero to the home page with public/hero.mp4 playing behind the headline.
Use a <video> with autoplay, muted, loop and playsinline, poster public/hero-poster.jpg,
object-fit: cover, and public/hero-sm.mp4 below 768px. Add a dark gradient overlay so the
headline and buttons reach 4.5:1 contrast on every frame, and a pause button that works
with the keyboard. With prefers-reduced-motion, show the poster and don’t play.
Keep the headline as real text.

The markup it writes should look about like this:

HTML

<section class="hero">
  <video class="hero-video" autoplay muted loop playsinline
         poster="/hero-poster.jpg" aria-hidden="true">
    <source src="/hero-sm.mp4" type="video/mp4" media="(max-width: 767px)">
    <source src="/hero.mp4" type="video/mp4">
  </video>
  <div class="hero-copy">
    <h1>Ship it today.</h1>
    <a href="/signup">Get started</a>
  </div>
  <button class="hero-pause" type="button">Pause background video</button>
</section>

CSS

.hero { position: relative; display: grid; place-items: center; min-height: 80svh; overflow: hidden; }
.hero-video { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
.hero::after { content: ""; position: absolute; inset: 0;
  background: linear-gradient(to top, rgb(0 0 0 / 0.65), rgb(0 0 0 / 0.15)); }
.hero-copy, .hero-pause { position: relative; z-index: 1; }

JavaScript

const video = document.querySelector('.hero-video')
const button = document.querySelector('.hero-pause')
const label = () => {
  button.textContent = `${video.paused ? 'Play' : 'Pause'} background video`
}
// pause() before playback starts also cancels the autoplay.
if (matchMedia('(prefers-reduced-motion: reduce)').matches) video.pause()
button.addEventListener('click', () => (video.paused ? video.play() : video.pause()))
video.addEventListener('play', label)
video.addEventListener('pause', label)
label()

Step 3: check it

Before you ship the hero

The poster reads on its own: some browsers and power-saving modes block autoplay, and then the poster is all visitors see.
The headline and buttons pass 4.5:1 contrast over the brightest frame, not just the first one.
With reduced motion turned on in your system settings, the page shows the poster and nothing moves.
On a phone, the network panel shows hero-sm.mp4, not the full file.
The pause button can be reached with Tab and works with Enter or Space.
The headline is real text you can select, so search engines and screen readers get it.

A video that plays for more than five seconds on its own needs a way to pause it, under WCAG’s Pause, Stop, Hide rule. The button above covers that.

Or start from a hero skill

Lookbk’s hero skills do the file preparation, fallbacks and checks for you, test the page at four widths and record an MP4 of it for launch posts. Scroll Film Hero takes your own clip and plays it as the visitor scrolls, as a full-bleed background or in a window beside the copy. The Footage Heroes ship their own retro film, with the headline behind the subject.

Scroll Film Hero+3

Neon Motel Hero+3

Shuttle Launch Hero+3

See the best video background hero sections for how they compare, and Install a skill in Claude Code to add one.

How to add a video background hero with Claude Code

What you need

Step 1: prepare the video file

Step 2: ask Claude Code for the section

Step 3: check it

Or start from a hero skill

Common questions

Sources

Read next

Website background video: size, format and performance

Text-behind-subject website heroes: how they work and how to make one

How to install a skill in Claude Code

Make a product launch video with an AI agent

See a skill’s result before you install it.