The generic amp-video component plays videos directly on a page, much like a <video> tag.
Unfortunately, not all videos can be embedded this way. For these specialized cases, AMP provides vendor-optimized components like amp-youtube, amp-ima-video, and others.
Internally these players load an iframe whose page communicates with the outer document to coordinate playback.
We would prefer to not have additional custom video implementations. Instead we believe, amp-video-iframe should be used instead, since it is a generic component that can load any video document to coordinate playback. Instead, new integrations should come in the form of amp-video-iframe configurations. If you believe you're unable to integrate with amp-video-iframe, please file a bug report mentioning @alanorozco and @wassgha.
You probably do not need to build your own player.
The amp-video-iframe playback interface supports the following methods, which we believe cover the vast majority of cases AMP documents necessitate:
playpausemuteunmuteshowcontrolshidecontrolsfullscreenenterfullscreenexit
amp-video-iframe can also send custom namespaced analytics signals.
(If there is a feature missing from this list that a custom player requires, we are happy to work on extending it as necessary.)
If this is enough for your use case, you'd only need to build a playback document hosted on your server that's able to communicate with amp-video-iframe.
For guidance on accomplishing this, refer to the component documentation.
(If you cannot support these playback methods, it's likely that a simple amp-iframe
can embed a separate video document just fine.)
Once you host your integration document, you may provide a code sample for document authors to find your service in the AMP documentation.
If the API you require for communication includes methods that are not part of the amp-video-iframe playback interface, you might want to build your own player. (Please note that most custom analytics signals are not considered in this case,
since amp-video-iframe also has plumbing for that.)
For example, these are some of the features that justify specific players:
-
amp-youtubeloads initial-frame placeholder images based on a URL scheme for perceived performance. Its underlying implementation also loads with lower-than-default priority, since it's rather large in binary size. -
amp-ima-videoembeds a generic host-less page that ships with the IMA SDK in order to transparently include standard IMA interface videos.
(Please note that most other 3p players historically exist before amp-video-iframe could fulfill their use case.)
You'll need to go through the standard AMP contribution process when creating and submitting your component. For large features, such as a video player, you need to file an I2I (intent-to-implement) issue that describes the overall workings of your component.
Your player component is also shipped as an extension, so you should become familiar with the process of building one.
Every player component talks to a single VideoManager via standard methods (VideoInterface) and events (VideoEvents) defined in the AMP video interface.
This manager performs standard responsibilities for all videos, regardless of type:
- accessible, managed autoplay
- analytics tracking for playback
- coordination with
amp-story - docked video
- rotate-to-fullscreen
Component classes should implement the VideoInterface.
You can implement this interface entirely or partially, depending on the video integration features you'd like to support.
At the very least, you should implement play() and pause(). Likewise, playback
actions (like my-element.play) will not work when unimplemented.
Read through the VideoInterface code to understand the individual effects of leaving each method unimplemented.
Existing implementations for amp-youtube.js and amp-video-iframe.js are good starter examples for implementation details. They use several standard utilities for creating the video frame and communicating with the VideoManager.