# Video files

> Recommended settings for video on an Evolving Edge site: MP4 with H.264, the index at the start of the file, a poster image, and where to put the file so it's published.

Source: https://docs.evolvingedge.ai/video/

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.

## 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](https://docs.evolvingedge.ai/cli/#size-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

With [FFmpeg](https://ffmpeg.org/) installed, `ffprobe` shows the codecs and the container:

```sh
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.

## 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:

```sh
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:

```sh
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:

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

## 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

```html
<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.

## How the network serves video

- **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](https://docs.evolvingedge.ai/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](https://docs.evolvingedge.ai/headers/#caching-cache-control).
- **Encrypted sites.** For Level 1, play video through the browser SDK's video player, which decrypts it as it plays: see [Video playback](https://docs.evolvingedge.ai/workloads/#video-playback).

## Checking it after you deploy

```sh
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`.
