diff --git a/contributing/building-a-bento-amp-extension.md b/contributing/building-a-bento-amp-extension.md index dc14a7b024f2..e4217dcd8de8 100644 --- a/contributing/building-a-bento-amp-extension.md +++ b/contributing/building-a-bento-amp-extension.md @@ -670,8 +670,9 @@ $ amp check-types - [amp-timeago](https://github.com/ampproject/amphtml/pull/26507) - [amp-base-carousel](https://github.com/ampproject/amphtml/pull/29303) - [amp-stream-gallery](https://github.com/ampproject/amphtml/pull/30597) -- Adding video components which use `VideoWrapper` +- Adding video components which use `VideoWrapper`. [You may also follow the guide to Building a Bento Video Component.](./building-a-bento-video-player.md) - [amp-video](https://github.com/ampproject/amphtml/pull/30280) + - [amp-vimeo](https://github.com/ampproject/amphtml/pull/33971) - [amp-youtube](https://github.com/ampproject/amphtml/pull/30444) - Adding iframe based embeds - [amp-instagram](https://github.com/ampproject/amphtml/pull/30230) diff --git a/contributing/building-a-bento-video-player.md b/contributing/building-a-bento-video-player.md new file mode 100644 index 000000000000..859b5c8b072e --- /dev/null +++ b/contributing/building-a-bento-video-player.md @@ -0,0 +1,653 @@ +# Building a Bento Video Player + +> **You should first read through the [guide to Building a Bento AMP Component](./building-a-bento-amp-extension.md).** Do not follow the steps to generate an extension, since they're specified here. Once you're familiar with the concepts related to AMP extensions and Bento components, follow this guide instead. + + + + + +- [How Video Player Components Work](#how-video-player-components-work) +- [Getting Started](#getting-started) +- [Directory Structure](#directory-structure) +- [Extend `VideoBaseElement` for AMP](#extend-videobaseelement-for-amp) + - [Pre-upgrade CSS](#pre-upgrade-css) + - [`props`](#props) +- [Define a Preact component](#define-a-preact-component) + - [Forwarding `ref`](#forwarding-ref) + - [Loading an iframe with `VideoIframe`](#loading-an-iframe-with-videoiframe) + - [`src`](#src) + - [`origin`](#origin) + - [Playback methods with `makeMethodMessage`](#playback-methods-with-makemethodmessage) + - [Handling events with `onMessage`](#handling-events-with-onmessage) + - [Use `VideoWrapper` directly](#use-videowrapper-directly) + - [Specifying `component`](#specifying-component) + - [Passing or overriding props](#passing-or-overriding-props) + - [Imperative handle](#imperative-handle) +- [Completing your extension](#completing-your-extension) +- [Example Pull Requests](#example-pull-requests) + +## How Video Player Components Work + +AMP and Bento provide [default video player capabilities](https://amp.dev/documentation/guides-and-tutorials/learn/spec/amp-video-interface/) in order to create a uniform experience. For example, videos only autoplay while they're visible and muted, and they consistently unmute when clicked. They send the same event signals to [`amp-analytics`](https://go.amp.dev/c/amp-analytics), or may be pinned to a corner in the same way in combination with [`amp-video-docking`](https://go.amp.dev/c/amp-video-docking). + +On a host document, player components must dispatch the same events and implement the same methods so that playback and user interface can be coordinated successfully. + +**Preact components** can support this behavior by using a **`VideoWrapper`** that renders a specified `component`: + +```js +return +``` + +The `component` prop can be a string to specify a `