Video files
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:
- Use an MP4 file with H.264 video (and AAC audio, if it has sound).
- Put the file’s index at the start of the file (often called “faststart”).
- Make a poster image to show until the video plays.
- Put the files in your generator’s static folder, so they’re published as they are.
- Embed it with a
<video>element that has controls, a poster, its size and a description.
Recommended format
Section titled “Recommended format”| 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.
Checking a file
Section titled “Checking a file”With FFmpeg installed, ffprobe shows the codecs and the container:
ffprobe -v error -show_entries stream=codec_type,codec_name -show_entries format=format_name -of compact input.movLook for codec_name=h264 on the video stream and codec_name=aac on the audio stream, if there is one.
Preparing the file
Section titled “Preparing the file”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:
ffmpeg -i input.mov -map 0:v:0 -map '0:a:0?' -c copy -movflags +faststart output.mp4If it’s HEVC or another codec, re-encode it to H.264:
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.mp4A 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:
ffmpeg -ss 0.5 -i output.mp4 -frames:v 1 -vf scale=1200:-2 -q:v 3 poster.jpgWhere to put the file
Section titled “Where to put the file”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/.
Embedding the video
Section titled “Embedding the video”<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>widthandheightare the video’s own size. They keep the page from shifting as the video loads. Scale it to fit with CSS, for examplevideo { max-width: 100%; height: auto; }.preload="metadata"loads only the start of the file until the visitor presses play.posteris shown until the video plays.aria-labeldescribes 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.
How the network serves video
Section titled “How the network serves video”- Content type.
.mp4files are served asvideo/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.
Checking it after you deploy
Section titled “Checking it after you deploy”curl -sI https://www.example.com/media/demo.mp4curl -s -o /dev/null -w '%{http_code}\n' -r 0-1023 https://www.example.com/media/demo.mp4The first should show content-type: video/mp4 and accept-ranges: bytes. The second should print 206.
