Skip to content

Video files

View as Markdown

A video on your site is served like any other file. To make sure it plays in every browser and can start before it has fully downloaded, prepare it as described here before you deploy.

In short:

  1. Use an MP4 file with H.264 video (and AAC audio, if it has sound).
  2. Put the file’s index at the start of the file (often called “faststart”).
  3. Make a poster image to show until the video plays.
  4. Put the files in your generator’s static folder, so they’re published as they are.
  5. Embed it with a <video> element that has controls, a poster, its size and a description.
Setting Recommended Why
Container MP4 (.mp4) Plays in every current browser.
Video codec H.264, 8-bit (yuv420p) The most widely supported codec. HEVC (H.265), which phones and some screen recorders use, doesn’t play in every browser.
Audio codec AAC Supported wherever H.264 is. Leave the audio out if the video has none.
Index (moov) At the start of the file The browser needs the index before it can play anything. At the end, it has to fetch the end of the file first.
Size As small as looks right Video is already compressed, so it counts toward a deploy’s 1 GiB limit at about its full size. Keep each file under 256 MB.

Screen recordings deserve a check. A recording made with QuickTime or the macOS screenshot tool is often a QuickTime movie (.mov, or an .mp4 file marked as QuickTime inside), with its index at the end. Repackage it as below.

With FFmpeg installed, ffprobe shows the codecs and the container:

Terminal window
ffprobe -v error -show_entries stream=codec_type,codec_name -show_entries format=format_name -of compact input.mov

Look for codec_name=h264 on the video stream and codec_name=aac on the audio stream, if there is one.

If the video is already H.264, repackage it as MP4 with the index at the start. This copies the video and audio as they are, so the picture doesn’t change:

Terminal window
ffmpeg -i input.mov -map 0:v:0 -map '0:a:0?' -c copy -movflags +faststart output.mp4

If it’s HEVC or another codec, re-encode it to H.264:

Terminal window
ffmpeg -i input.mov -map 0:v:0 -map '0:a:0?' \
-c:v libx264 -crf 23 -preset slow -pix_fmt yuv420p \
-c:a aac -b:a 128k -movflags +faststart output.mp4

A higher -crf gives a smaller file and a softer picture. To make a large screen recording smaller, you can also scale it down while re-encoding, for example to 1920 pixels wide, by adding -vf scale=1920:-2.

Make a poster image from a frame half a second in:

Terminal window
ffmpeg -ss 0.5 -i output.mp4 -frames:v 1 -vf scale=1200:-2 -q:v 3 poster.jpg

Put the video and its poster in the folder your generator copies to the site unchanged, and link to them by their path from the root of the site (for example /media/demo.mp4):

Generator Folder
Astro, Vite public/
VitePress public/ inside your docs folder (for example docs/public/)
Hugo, Docusaurus static/
Jekyll Any folder whose name doesn’t start with _

In Astro, a file in src/assets/ is published only when code imports it, and a Markdown page can’t import a video. A video there isn’t deployed, so use public/.

<video controls muted playsinline preload="metadata"
width="1920" height="1080"
poster="/media/demo.jpg"
aria-label="A short description of what the video shows.">
<source src="/media/demo.mp4" type="video/mp4">
<a href="/media/demo.mp4">Download the video (MP4)</a>
</video>
  • width and height are the video’s own size. They keep the page from shifting as the video loads. Scale it to fit with CSS, for example video { max-width: 100%; height: auto; }.
  • preload="metadata" loads only the start of the file until the visitor presses play.
  • poster is shown until the video plays.
  • aria-label describes the video for screen readers. If the video has speech, add captions with a <track> element.
  • The link inside is shown by browsers that can’t play the video.

To play a short clip on its own, like an animated image, use autoplay muted loop playsinline in place of controls. Browsers only autoplay video that is muted. Keep such clips short, and consider leaving them paused for visitors who have asked for reduced motion.

Markdown pages can contain this HTML as it is.

  • Content type. .mp4 files are served as video/mp4.
  • Seeking. Requests for part of a file are answered with 206 Partial Content, so visitors can skip ahead without downloading the whole file. These requests, and files over about 16 MB, come from Regional gateways: see Delivery from operator nodes.
  • Caching. Like other files outside your generator’s hashed folder, a video is cached for an hour by default. If you replace a video, give the new one a new file name so visitors don’t see the old one for up to an hour, or set your own caching with response headers.
  • Encrypted sites. For Level 1, play video through the browser SDK’s video player, which decrypts it as it plays: see Video playback.
Terminal window
curl -sI https://www.example.com/media/demo.mp4
curl -s -o /dev/null -w '%{http_code}\n' -r 0-1023 https://www.example.com/media/demo.mp4

The first should show content-type: video/mp4 and accept-ranges: bytes. The second should print 206.