Video
The video field: a YouTube or Vimeo video, a media library video or an .mp4/.webm file on an allowed host, with poster, captions confirmation, title and transcript, rendered through a privacy facade.
A video field references one video. It never embeds a third party’s player on page load: the template renders a facade, the poster and a play button naming the video, and loads the player only when the visitor activates it, from YouTube’s no-cookie domain or with Vimeo’s do-not-track flag.
fields:
- name: film
type: video
sources: [youtube, vimeo]
poster: required
captions: required
transcript: true
- name: backgroundLoop
type: video
sources: [file]
hosts: [media.example.org, self]
poster: required
captions: none Parameters
| Parameter | Type | Default | What it does |
|---|---|---|---|
sources | list of youtube, vimeo, library, file | [youtube, vimeo] | What may be chosen. library is a video reference from the media library; file is an .mp4 or .webm on an allowed host. |
hosts | list of host names | none | Required with file: the hosts a file may come from. self allows a path to one of the project’s own public files, such as /video/harbour.mp4. |
poster | required or optional | optional | The still shown before playing: a library image, else the provider’s thumbnail, which the server fetches once and keeps in the library. required makes publishing need one. |
captions | required, warn or none | warn | Whether publishing asks the editor to confirm the video has captions: required refuses without the confirmation, warn publishes with a warning, none does not ask. |
transcript | boolean | false | Offers a transcript, rich text per locale. |
structure | shared or per_locale | shared | per_locale makes the whole video each locale’s own (a different film per language). |
engine-dmo check refuses an unknown source, file without hosts, hosts without file, and values outside the lists above.
Validation
| Code | Message |
|---|---|
video_choose | Paste a video’s address or choose one from the library |
video_url | Paste the address of a youtube, vimeo video |
video_source | This field does not take vimeo videos |
video_id_youtube, video_id_vimeo | This is not a YouTube / Vimeo video’s address |
video_file | A video file’s address starts with https:// |
video_host | Video files may only come from media.example.org |
video_file_type | A video file is an .mp4 or a .webm |
video_library | Choose a video from the library |
video_title | Enter the video’s title; it names the player for screen readers (in the source locale) |
video_start | The start is a number of seconds from the beginning |
video_duration | Write the duration as minutes and seconds, such as 3:33 |
video_poster, video_poster_choose | Choose a poster image for the video (at publish, with poster: required) |
video_captions | Confirm the video has captions before publishing (captions: required) |
video_captions_unconfirmed | Warning: the video is not confirmed as captioned (captions: warn) |
transcript_offered | This field does not take a transcript |
Stored value
{
"source": "youtube", "id": "aqz-KE-bpKQ", "start": 30,
"title": "A walk along the harbour wall",
"poster": { "asset": "3c1e..." },
"captions": true,
"duration": "PT3M33S",
"transcript": [ { "_type": "block", "_key": "t1", "children": [ { "_type": "span", "text": "..." } ] } ]
} A Vimeo video may carry hash (an unlisted video’s), a file source has url instead of id, and a library source has asset. The editor pastes a watch page’s address and the engine reads the id from it. title and transcript are each locale’s own; everything else is shared by every locale. With index: true the poster and library asset ids are projected.
Template value
Printing the value prints the watch page’s URL.
| Property | What it is |
|---|---|
title | The video’s title, the player’s accessible name. |
source, id | youtube, vimeo, library or file, and the provider’s id. |
start, duration | Where playing starts in seconds, and the length as ISO 8601. |
captions | Whether the editor confirmed captions. |
watchUrl, embedUrl | The provider’s page, and the player on its privacy domain. |
poster | The poster as an image value, with img, picture, figure, transform and url. |
transcript | The transcript as Portable Text. |
| Method | What it writes |
|---|---|
render(transform=, sizes=, priority=, element=) | The facade: the poster and a play button naming the video, loading nothing from the provider until activated. element is figure (the default) or div. Other keywords are the wrapper’s attributes. |
background(transform=) | A muted, looping, inline file video for decoration, with a pause button. Refused without a poster, and never plays under reduced motion or Save-Data. |
link(text=) | A plain link to the watch page, for a list or an email. |
{% if entry.film %}
{{ entry.film.render(transform="hero") }}
{% if entry.film.transcript %}<details><summary>Transcript</summary>{{ entry.film.transcript|ptext }}</details>{% endif %}
{% endif %} For a video that is not a field (a provider link pasted in rich text or a template’s own embed), see embed() in Globals.
Link
The link field (one link or a list) to a document, asset, URL, email address, phone number, site or anchor, with kinds and their settings, editor attributes, rel, named styles, sub-fields, the stored shape and the link value templates receive.
SEO
The seo field: a per-locale search title and description and their social-sharing pair, with length warnings, the stored shape, and how head() uses it.