# `<VideoPlayer/>` component for easy video integration.

`<VideoPlayer />` is a Vue component specially designed to work seamlessly with
DatoCMS’s [`video` GraphQL query][q]) that optimizes video streaming for your
sites.

[q]: https://www.datocms.com/docs/content-delivery-api/images-and-videos#videos

To stream videos, DatoCMS partners with MUX, a video CDN that serves optimized
streams to your users. Our component is a wrapper around 
[MUX's video player][mvp] [web component][wc]. It takes care of the details for you, and this
is our recommended way to serve optimal videos to your users.

[mvp]: https://github.com/muxinc/elements/blob/main/packages/mux-player/README.md
[wc]: https://developer.mozilla.org/en-US/docs/Web/API/Web_components

## Out-of-the-box features

- Offers optimized streaming so smartphones and tablets don’t request desktop-sized videos
- Lazy loads the underlying video player web component and the video to be
  played to speed initial page load and save bandwidth
- Holds the video position so your page doesn’t jump while the player loads
- Uses blur-up technique to show a placeholder of the video while it loads

## Table of Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**

- [Installation](#installation)
  - [Setup](#setup)
- [Usage](#usage)
- [Props](#props)
- [Opt-in Viewer Analytics](#opt-in-viewer-analytics)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->


## Installation

```sh
npm install --save vue-datocms @mux/mux-player
```

`@mux/mux-player` is a [peer dependency][pd] for `vue-datocms`: so you're
expected to add it to your project.

[pd]: https://docs.npmjs.com/cli/v10/configuring-npm/package-json#peerdependencies

### Setup

You can register the component globally so it's available in all your apps:

```js
import Vue from 'vue';
import { DatocmsVideoPlayerPlugin } from 'vue-datocms';

Vue.use(DatocmsVideoPlayerPlugin);
```

Or use it locally in any of your components:

```js
import { VideoPlayer } from 'vue-datocms';

export default {
  components: {
    'datocms-video-player': VideoPlayer,
  },
};
```

## Usage

```vue
<template>
  <article>
    <div v-if="data">
      <h1>{{ data.blogPost.title }}</h1>
      <datocms-video-player :data="data.blogPost.video" />
    </div>
  </article>
</template>

<script>
import { request } from './lib/datocms';
import { VideoPlayer } from 'vue-datocms';

// The GraphQL query returns data that the `VideoPlayer` component
// automatically uses to properly size the player, set up a “blur-up”
// placeholder as well as lazy loading the video.
const query = gql`
  query {
    blogPost {
      title
      cover {
        video {
          # required: this field identifies the video to be played
          muxPlaybackId

          # all the other fields are not required but:

          # if provided, title is displayed in the upper left corner of the video
          title

          # if provided, width and height are used to define the aspect ratio of the
          # player, so to avoid layout jumps during the rendering.
          width
          height

          # if provided, it shows a blurred placeholder for the video
          blurUpThumb

          # if provided, it enables DatoCMS Content Link for click-to-edit overlays
          alt

          # you can include more data here: they will be ignored by the component
        }
      }
    }
  }
`;

export default {
  components: {
    'datocms-video-player': VideoPlayer,
  },
  data() {
    return {
      data: null,
    };
  },
  async mounted() {
    this.data = await request({ query });
  },
};
</script>
```

## Props

The `<VideoPlayer />` component supports as props all the
[attributes][attributes] of the `<mux-player />` web component, plus `data`,
which is meant to receive data directly in the shape they are provided by
DatoCMS GraphQL API.

[attributes]: https://github.com/muxinc/elements/blob/main/packages/mux-player/REFERENCE.md

`<VideoPlayer />` uses the `data` prop to generate a set of attributes for the
inner `<mux-player />`.

| prop | type           | required           | description                                                      | default |
| ---- | -------------- | ------------------ | ---------------------------------------------------------------- | ------- |
| data | `Video` object | :white_check_mark: | The actual response you get from a DatoCMS `video` GraphQL query |         |

`<VideoPlayer />` generate some default attributes:

- when not declared, the `disable-cookies` prop is true, unless you explicitly
  set the prop to `false` (therefore it generates a `disable-cookies` attribute)
- when not declared, the `preload` prop defaults to `metadata`, for an optimal UX experience together with saved bandwidth
- the video height and width, when available in the `data` props, are used to
  set a default `aspect-ratio: [width] / [height];` for the `<mux-player />`'s
  `style` attribute

All the other props are forwarded to the `<mux-player />` web component that is used internally.

## Opt-in Viewer Analytics

This `<VideoPlayer/>` component can OPTIONALLY collect clientside [playback and engagement metrics](https://www.mux.com/data#TechSpecs) such as playback percentages, user agents, and geography.

These analytics are **disabled** by default. To enable them, you must opt in to [Mux Data](https://www.mux.com/data) integration by creating a Mux Data account (free) and providing its `envKey` to the component.

For details and setup instructions, please see our documentation on **[Streaming Video Analytics with Mux Data](https://www.datocms.com/docs/streaming-videos/streaming-video-analytics-with-mux-data)**.