> YouTube, Vimeo and Instagram videos in a story as click-to-play posters. The page asks the video site for nothing until a reader presses play. Each site chooses its providers; off by default. Built, not released yet.

Canonical: https://p.apyr.us/video-embeds.html

# Video embeds

A story can show a video the story is about. An editor writes one line, the way a picture is written:

```
::video{src="https://youtu.be/UytYrhYLOKI" title="Aircraft sound localisation demonstration" caption="Two microphones, one jet." credit="Example Channel"}
```

The page does not load the video. It shows a poster, a real play button named by the title, and a plain link to the video for readers without JavaScript. Nothing on the page contacts YouTube, Vimeo or Instagram until a reader presses play. Then a small script puts that site's player in the poster's place. A reader who never presses play never talks to the video site.

This is built and tested. It is not released yet.

## The editor writes five things

- **src**: the address of the video. YouTube, Vimeo and Instagram addresses are known.
- **title**: the player's accessible name. It is required.
- **credit**: who made the video. It is required, because third-party media is always credited. The credit links to the video.
- **caption** and **start**: optional. The caption says what the reader will see before pressing play; start is whole seconds, where the video site allows it.

An Instagram post has no thumbnail we may copy, so its line also names a **poster**: a picture in the site's own storage. YouTube and Vimeo posters are copied into the site's storage once, by an operator, with `papyrus stories capture-video-posters`. Until a copy exists the page shows a flat placeholder with the title, never a broken image.

## Each site chooses its providers

Which video sites play is one setting in the site's `projection.json`:

```json
"embeds": { "providers": ["youtube", "vimeo", "instagram"] }
```

The list is empty by default, and an empty list means the feature is not there: Papyrus does not read `::video` at all, the site publishes the same files it did, and a site's own code keeps any video handling it has. With providers listed, a video from a known site that is not on the list shows as a plain line with the title linked to the video and the credit, and no player.

The site also gets a one-line Content-Security-Policy fragment that allows frames from the listed providers and nothing else, so a site that lists only YouTube cannot frame anything from Vimeo.

## Checked before it publishes

The four-lens review checks every video: a missing title or credit is a problem that blocks, a missing caption is a warning, a video whose provider the site has not listed is a warning, and a credited video that is not among the story's citations is flagged.

The details are in the Papyrus repository, in `docs/markus-content-markup.md` (Videos) and `docs/standard-site.md` (Video embeds), including how a site that embeds Instagram with its own code moves over.
