# Content Type: Video

Changes to how this Type behaves are requested through a GitHub Issue and implemented, together with this reference page, through the repository's normal workflow. See /_docs/posts for how Content Types, Roles, and Rank work in general, and docs/Internal/type-doc-templates.md for the Content Type Doc template this file follows.

A video clip attached to a Post — a briefing recording, a gallery entry, a demo. Same shape and behavior as Image and Audio, just for moving pictures.

## Where it comes from

Ingested one of three ways — see /_docs/media for the full mechanics:

- **Upload** — a file, drag-dropped, pasted, or chosen from a file picker. Local Upload/Fetch by URL is restricted to **MP4 and WebM** — the file's actual contents are verified, not just its name/extension.
- **Fetch by URL** — paste a URL and the server downloads and stores the file itself. Same MP4/WebM restriction as Upload.
- **Embed** — a hand-provided embed snippet (e.g. a YouTube or Vimeo embed code), keeping the video off-site entirely. An embedded Video has no local file at all, and isn't subject to the MP4/WebM restriction (a third-party provider's own formats apply).

## Fields

- **The video itself** (mandatory) — a locally-stored file (Upload/Fetch by URL) or an embed snippet (Embed). Stored and served verbatim — no transcoding to a different format/resolution yet (see /_docs/roadmap). Immutable once created, same as every Content Type.
- **Caption** (key optional) — text shown alongside the video.
- **Descriptive metadata** (optional) — a label, description, alt text, creator/attribution, rights, source label, and source URL, the same field set Image has. The **description** and **creator** fields feed directly into the public caption shown below every inline player; the **source label**/**source URL** pair (Via-link) is a plain editable field pair here — not a real, health-checked managed Link — see "Semantic HTML and accessibility" below for why.
- **Technical metadata** (specialist) — for a locally-stored Video only: duration, container/codec, resolution, rotation/orientation, frame rate, bit rate, and (when present) an embedded audio track's codec/channel count. Extracted automatically after upload, best-effort — never blocks or invalidates the upload, and never overwrites Caption/Role/Reference. Shown read-only on the element's metadata page and in Admin diagnostics.
- **Thumbnail** (specialist) — a representative still image, generated automatically for a locally-stored Video shortly after it's added (not the first frame — several candidates are sampled and near-black/blank ones rejected). Admin can override it with an exact timestamp or a fully custom uploaded still, and restore automatic generation at any time. Metadata/derived media of the Video element itself, not a separate Content Element — doesn't affect ordering, doesn't get its own Role/Rank. Not applicable to an Embed (no local file to derive a frame from) — a generic Video icon is shown instead wherever the thumbnail would appear.

## Semantic HTML and accessibility

Renders as a native `<video controls>` (`MediaElement.tsx`) for a locally-stored Video, or the admin-provided embed snippet verbatim for an Embed row. The active thumbnail (see Fields, above) is set as the `<video>` element's `poster` — every major browser shows a play affordance centered on it before playback starts, which is what keeps a Video from being mistaken for a plain Image wherever it appears without active playback. No captions/subtitles track is generated or attached — a visitor relies on the video's own audio, or the Caption/Description field's plain visible text alongside it, not a synced transcript.

A composed caption — "Description *(Credit: Creator, via Source)*," each part omitted when absent — renders directly below every inline player when there's anything to show. Immediately below that (or below the bare player, when there's no caption to show) is an **Info** link/control to this Video's own standalone metadata page: a right-aligned text link below the player, since this codebase's native `<video controls>` has no reliable, accessible way to add a custom icon into its own browser-drawn control bar. The link has a real accessible name, visible keyboard focus, and the same destination in public display and Admin Preview — omitted only for a decorative use or the metadata page itself (nothing to link to from there).

**Compact tile information control:** wherever a Video is shown as a compact grid/matrix tile rather than the full inline player above — Additional Information's Media group, Gallery's own matrix, and the three social Post Types' inline Media grid (see "Rendering contexts" below) — the tile is wrapped in the same hover overlay Image's own tile uses, exposing a small "i" **Video information** control on pointer hover, on keyboard focus, and permanently on touch devices (no hover state there to reveal it) — same position, size, and contrast as Image's own overlay control, reusing its exact styling rather than a divergent one. It's a separate, independently-labeled control alongside the tile's own link, not nested inside it, so activating it never interferes with selecting the tile itself. Both currently lead to the same standalone metadata page — a compact Video tile has no separate in-place preview the way Image's own fullscreen viewer is, so there's nothing else for the info control to distinguish itself from; it exists for the same discoverability/consistency reason Image's own control does.

Via-link stays a simple source-label/source-URL field pair — Video doesn't get live link-health checking or an archive-fallback status icon for its own source the way a real managed Link elsewhere on the site does. This is a deliberate scope choice, not an oversight; a fuller managed-Link-based citation mechanism is a candidate for a future issue if ever needed.

## Role, Rank, and Reference

A Post can hold several Videos at once, each with its own Role, or several sharing the same Role (e.g. a `gallery`), distinguished by Rank — see /_docs/posts. Every Video also has an optional **Reference** — a separate, Post-unique name for addressing it inline instead of by Role/Rank — see /_docs/posts's "Reference: inline addressing" for the full detail.

## Editing

In the admin Post editor, the Videos section holds one block per Video, with the same Upload / Fetch by URL / Embed controls, Role field, Position (Rank) field, caption field, and Metadata section (Description/Author/Via-link) as Images. Every Post Type's editor shows the same Videos section regardless of which Type is active.

## Rendering contexts

### Inline

A single-Role Video can be inline-embedded from markdown the same way as an Image, e.g. `{{briefing-video}}` — see /_docs/markdown for the full content reference syntax. The composed Description/Author/Via-link caption and the Info link (see "Semantic HTML and accessibility," above) both render here too, exactly as they do everywhere else this Type appears.

### Additional Information "Media" group

Every Post Type's shared Additional Information container has one combined **Media** mini-gallery holding every eligible Image, Video, and Audio together, in Rank-then-stable-order. A Video's own tile shows its active thumbnail (see Fields, above) with an always-visible play-affordance badge so it's never mistaken for a still Image — a stable generic Video icon when no thumbnail is ready yet, never a broken image. Selecting a Video's tile opens its own standalone metadata page (its existing player/playback flow), not a new in-page fullscreen video viewer; the same tile also exposes the hover/focus/touch "i" information control described above, to the same destination. Video keeps the ordinary "shown once" rule — no duplication exception: a `gallery`-role Video already shown by Gallery's own primary grid (images always shown first, then videos — see docs/PostTypes/gallery.md) doesn't also appear again here.

### Post metadata-page traversal

Every Video the Post has ever held (current Version, or full history via `/metadata/history`) is enumerated with its caption, descriptive metadata, and URL as JSON-LD/native JSON — see /_docs/posts's Metadata page section.

### Standalone Content Element page

`/_element/video/:id` shows the video itself, its composed Description/Author/Via-link caption, and its available normalized technical metadata (duration, resolution, codec, frame rate, and so on — absent fields simply omitted), gated exactly like the owning Post's own page.