Immersive video gallery (Expose-style)

Use immersive video when a plate should feel like a Live Photo: a cover still first, then a muted looping clip once the video is ready. This is still the same folder-backed ::gallery model — not a new content type, and not Expose polygon / spatial overlay scope.

Requires a Web Device runtime that includes cover+video immersion (arc#3764). Older builds still expand ::gallery{folder} and show covers; they may not crossfade into video. Upgrade the serving ARC build before treating a still-only plate as a broken sample.

Sized plates (ratio / width / height) need a runtime that includes sized-plate CSS; older builds keep full-viewport stage. Parameter details: Folder-backed media gallery.

When to use

Minimal example

::gallery{folder="plates" layout="expose"}

In-article square plate (reading column, no full-viewport scroll tax):

::gallery{folder="plates" layout="expose" ratio="1:1"}

This page keeps samples in ./plates/ so covers and videos ship in the repo (no hotlinks). License notes: plates/_ATTRIBUTION.md.

Authoring: layouts

Immersion comes from cover+video pairing in the folder, not from a separate layout engine.

Browse layouts (grid, mosaic, pair, masonry, film) and still-only large / stage plates without a video sibling stay as documented on Folder-backed media gallery. Pairing rules below still apply if a browse layout encounters video files; immersion UX is designed for stage / expose / story.

Authoring: plate size

Stage defaults to full viewport. For demos that should sit in the reading column (square Live Photo, 16 hero, fixed height), pass any combination of:

With only ratio, width defaults to min(100%, 36rem). Full parameter contract and error cases: Folder-backed media gallery — sized plates.

Cover + video pairing

Same-stem (Live Photo–like)

Put a still and a video that share the filename stem:

plates/
  01-bay.jpg
  01-bay.mp4
  01-bay.md          # optional sidecar

Accepted video extensions include mp4, webm, and mov (same stem as the cover image). Image extensions follow the gallery still set (jpg, jpeg, png, webp, …).

The cover is the plate member the gallery orders and captions; the matching video is the immersive motion layer for that plate.

Sidecar video: / poster:

When stems cannot match (or you rename assets), declare the pair in the plate sidecar:

---
title: Bay
overlay: bottom-left
tone: dark
video: clips/bay-loop.mp4
poster: covers/bay.jpg
---

Optional second line on the plate.

Paths in video: / poster: are resolved under the gallery folder (item-local), same as other gallery media — not site-level content/media/.

Use either same-stem or explicit sidecar fields for a plate; keep one clear pairing so authors and reviewers can see the contract in the folder.

Expected runtime behavior

Demos on this page strip audio so the muted loop is the whole story; shipping a clip with audio is allowed — expect Unmute, not autoplay with sound.

How this differs from other gallery modes

Do not invent Expose polygon masks, multi-layer spatial overlays, or a separate “expose content type” — those are out of scope for ::gallery.

Live sample

Same folder for every sample below: folder="plates" on this document.

Folder members:

Expose sized square (ratio="1:1")

In-article demo: same pairing, constrained plate.

::gallery{folder="plates" layout="expose" ratio="1:1"}

Cover stills first. When a plate has a paired video, the runtime crossfades into a muted loop.

Expose full viewport (layout="expose")

::gallery{folder="plates" layout="expose"}

Cover stills first. When a plate has a paired video, the runtime crossfades into a muted loop.

Stage (same immersion; expose is an alias)

::gallery{folder="plates" layout="stage"}

Cover stills first. When a plate has a paired video, the runtime crossfades into a muted loop.

Story (scroll plates; same pairing)

::gallery{folder="plates" layout="story"}

Cover stills first. When a plate has a paired video, the runtime crossfades into a muted loop.

What you should see (with arc#3764+): plates 01–03 show cover, then muted looping video; plate 04 stays still. Overlay titles come from sidecars. The sized square sample keeps that immersion inside a reading-column box. On older ARC, covers and stills still render; motion or sizing may be absent until the runtime is upgraded.

Errors and empty states

Boundaries

Related