Description A replacement for the HTML5 video tag; only to be used for direct HTML5 video file embeds.
Required Script <script async custom-element="amp-video" src="https://cdn.ampproject.org/v0/amp-video-0.1.js"></script>
Examples AMP By Example's:
Supported Layouts fill, fixed, fixed-height, flex-item, nodisplay, responsive

Behavior

The amp-video component loads the video resource specified by its src attribute lazily, at a time determined by the runtime. You can control an amp-video component much the same way as a standard HTML5 <video> tag.

The amp-video component accepts up to four unique types of HTML nodes as children:

  • source tags: Just like in the HTML <video> tag, you can add <source> tag children to specify different source media files to play.
  • track tags to enable subtitles in the video. If the track is hosted on a different origin than the document, you must add the crossorigin attribute to the <amp-video> tag.
  • a placeholder for before the video starts
  • a fallback if the browser doesn’t support HTML5 video: One or zero immediate child nodes can have the fallback attribute. If present, this node and its children form the content that displays if HTML5 video is not supported on the user’s browser.

Example

Show full code

Attributes

src

Required if no <source> children are present. Must be HTTPS.

poster

The image for the frame to be displayed before video playback has started. By default, the first frame is displayed.

Alternatively, you can present a click-to-play overlay. For details, see the Click-to-Play overlay section below.

autoplay

If this attribute is present, and the browser supports autoplay:

  • the video is automatically muted before autoplay starts
  • when the video is scrolled out of view, the video is paused
  • when the video is scrolled into view, the video resumes playback
  • when the user taps the video, the video is unmuted
  • if the user has interacted with the video (e.g., mutes/unmutes, pauses/resumes, etc.), and the video is scrolled in or out of view, the state of the video remains as how the user left it. For example, if the user pauses the video, then scrolls the video out of view and returns to the video, the video is still paused.
controls

This attribute is similar to the controls attribute in the HTML5 video. If this attribute is present, the browser offers controls to allow the user to control video playback.

loop

If present, the video will automatically loop back to the start upon reaching the end.

crossorigin

Required if a track resource is hosted on a different origin than the document.

muted (deprecated)

The muted attribute is deprecated and no longer has any effect. The autoplay attribute automatically controls the mute behavior.

common attributes

This element includes common attributes extended to AMP components.

Media Session API Attributes

amp-video implements the Media Session API enabling developers to specify more information about the video file that is playing to be displayed in the notification center of user's devices (along with play/pause controls).

artwork

URL to a PNG/JPG/ICO image serving as the video's artwork. If not present, the MediaSessionAPI Helper will use either the image field in the schema.org definition, the og:image or the website's favicon.

artist

(string) indicates the author of the video file

album

(string) indicates the album/collection the video was taken from

title

(string) part of the common attributes, doubles as the video's name/title displayed in the MediaSession notification. If not provided, the MediaSessionAPI Helper will use either the aria-label attribute or fall back to the page's title.

Example:

Note that this example has both the poster and artwork attributes, poster will be used as the placeholder before the video plays while artwork is the image that will be displayed in the notification throught the MediaSessionAPI.

<amp-audio width="400" height="300"
  src="https://yourhost.com/audios/myaudio.mp3"
  poster="https://yourhost.com/posters/poster.png"
  artwork="https://yourhost.com/artworks/artwork.png"
  title="Awesome music" artist="Awesome singer"
  album="Amazing album">
  <source type="audio/mpeg" src="foo.mp3">
</amp-audio>

Click-to-Play overlay

Providing a click-to-play overlay is a common UX feature for video players on the web. For example, you could display a custom play icon that the user can click, as well as include the title of the video, different sized poster images, and so on. Because the amp-video component supports the standard play AMP action, you can easily implement click-to-play.

For a detailed example, visit AMP By Example's Click-to-play overlay for amp-video.

Validation

See amp-video rules in the AMP validator specification.