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.