---
category: packages
---

# @instructure/ui-media-player

A cross-browser HTML5 media player built from the ground up using React. UI-Media-Player supports many custom options and views with opportunities to provide custom content via <MediaPlayer.Overlay>.

### Features

- Compatible with Instructure-UI ([https://instructure.design/](https://instructure.design/))
- Accessible out of the box
- Themeable by design

## Getting Started

### Requirements

In order to utilize `ui-media-player` you must have the following packages present in your library...

- React `15 || 16`
- ReactDOM `15 || 16`

### Browser Support

- Chrome, Safari, Firefox, Edge (last two versions)

### Installation

Add the package to your project using either `npm` or `yarn`.

#### NPM

```
npm i @instructure/ui-media-player
```

#### Yarn

```
yarn add @instructure/ui-media-player
```

## Versioning

The UI-Media-Player uses [SemVer](https://semver.org/) for versioning.

## MediaPlayer Components

### `<MediaPlayer>`

#### Usage

```
<MediaPlayer
  disableRightClick
  poster="image/bigBuckBunnyPoster.png"
  sources={[
    {
      label: "1080p",
      src: "big_buck_bunny_1080p.mp4",
      defaultSelected: true
    },
    {
      label: "360p",
      src: "big_buck_bunny_360p.mp4"
    }
  ]}
  tracks={[
    {
      src: "big_buck_bunny_captions.srt",
      label: "English",
      type: "subtitles",
      language: "en"
    }
  ]}
  customControls={[
    name: 'Comments',
    label: 'Toggle comments',
    onClick: () => setCommentVisibility(!commentsVisible),
    checked: commentsVisible
  ]}
/>
```

#### PropTypes

| Prop               | Type               | Default   | Description                                                                                                                                                     |
| ------------------ | ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| actionsRef         | func               |           | Function to be run on the ref of the actions component that returns functionality such as playVideo, pauseVideo, seekTo, and others.                            |
| alwaysShowControls | bool               | `false`   | If set to true, the controls will never dismiss                                                                                                                 |
| captionOffset      | number \|\| string | `0`       | Indicates the caption offset measurement for captions. Providing a number simply adds to the current measurement while a string will override the entire value. |
| captionPosition    | string             | `'top'`   | Indicates the named position of the captions. `'top'`, `'bottom'`, `'left'`, or `'right'`                                                                       |
| children           | children           |           | Only accepts <MediaPlayer.Overlay> as a child to display information overtop of the video player                                                                |
| customControls     | array              |           | Additional controls to be added to the settings menu. Each object must contain values for `name`, `label`, `onClick`, and `checked`                             |
| disableRightClick  | bool               | `false`   | Disable right click on the player container                                                                                                                     |
| getSettings        | func               |           | Function to return an object with the saved settings                                                                                                            |
| hideFullScreen     | bool               | `false`   | If set to true, FullScreenButton is hidden                                                                                                                      |
| label              | string             | `''`      | Give the player a label to be read by screen readers                                                                                                            |
| markers            | array              | `[]`      | Accepts <MediaPlayer.Marker> components in an array                                                                                                             |
| poster             | string             |           | The poster image to use before the media is played                                                                                                              |
| savePlayerSettings | func               |           | A callback function to call when one of the supported settings changes                                                                                          |
| sources            | array              | `[]`      | URL(s) of video to play. Each object in a provided array must contain values for both `src`,`label`, and optionally `defaultSelected`.                          |
| tracks             | array              | `[]`      | Tracks of the video to play. Each object must contain values for `src`, `label`, `type`, and `language`                                                         |
| translations       | object             | `{}`      | Label overrides for i18n. Defaults to english.                                                                                                                  |
| type               | string             | `'video'` | One of type `'video'` or `'youtube'`                                                                                                                            |
| startAt            | number             | `0`       | Indicates the start time the media should be played back from                                                                                                   |
| _fluidHeight_      | bool               | `false`   | _DEPRECATED_ Indicates the player should fill the height of its container                                                                                       |
| _fluidWidth_       | bool               | `true`    | _DEPRECATED_ Indicates the player should fill the width of its container                                                                                        |

#### Supported settings

| Key             | Type   | Default    | Description                                                             |
| --------------- | ------ | ---------- | ----------------------------------------------------------------------- |
| captionPosition | string | `'bottom'` | Position of the caption. One of type `'bottom'` or `'top'`              |
| captionColor    | string | `'dark'`   | Color scheme of the caption. One of type `'dark'` or `'light'`          |
| captionFontSize | string | `'normal'` | Size of the caption text. One of type `'norma'`, `'large'` or `'extra'` |
| volume          | number | 1          | Volume of the player. Value must be between 0 and 1                     |
| playbackSpeed   | number | 1          | Playback rate of the media. Value must be between 0.5 and 2             |

#### Translations

Translations are supported in `<MediaPlayer>` and allow the following labels to be overridden from their defaults of English.

See in src/constants/translated/translations.js

##### Example

```
<MediaPlayer
  {...otherProps}
  translations={{
    VOLUME_UNMUTED: "Volume",
    VOLUME_MUTED: i18n.t('muted') // Functions that return a string are also valid
  }}
/>
```

### `<MediaPlayer.Marker>`

#### Usage

```
<MediaPlayer
  {...otherProps}
  markers={[
    <MediaPlayer.Marker
      active
      hoverIcon={<HoverIcon />}
      icon={<TimerIcon />}
      label="A Marker"
      onClick={() => {}}
      onReached={() => {}}
      time={someTime}
      variant="circle"
    />
  ]}
/>
```

#### PropTypes

| Prop      | Type   | Default    | Description                                                                                   |
| --------- | ------ | ---------- | --------------------------------------------------------------------------------------------- |
| active    | bool   | false      | Describes if the Player Marker is active                                                      |
| hoverIcon | node   |            | A component that is displayed when the user hovers over the marker                            |
| icon      | node   |            | Icon used to represent the marker inside the Timebar                                          |
| id        | string | Required   | Id value must be unique in order for focus management to work properly inside the MediaPlayer |
| label     | string | ''         | Label for the Marker                                                                          |
| onClick   | func   | `() => {}` | Function that is called on click of the marker                                                |
| onReached | func   |            | Function that is called upon reaching the marker location                                     |
| time      | number | 0          | Represents the time at which the marker will be triggered and fired `onReached`               |
| variant   | string | `'hidden'` | One of type `'circle'` or `'hidden'`                                                          |

### `<MediaPlayer.Overlay>`

#### Usage

```
<MediaPlayer
  {...props}>
  <MediaPlayer.Overlay
    >
    () => (
      <div>Content for the overlay</div>
    )
  </MediaPlayer.Overlay>
</MediaPlayer>
```

#### PropTypes

| Prop         | Type     | Default | Description                                                                     |
| ------------ | -------- | ------- | ------------------------------------------------------------------------------- |
| children     | function |         | Function that renders content to be displayed in the Overlay of the MediaPlayer |
| hideControls | bool     | `false` | Hide the control bar completely                                                 |

### `<MediaPlayer.Playhead>`

#### Usage

```
<MediaPlayer
  playhead={
    <MediaPlayer.Playhead
      label="A Playhead"
      onClick={() => {}}
      variant="button"
      >
  } />
```

#### PropTypes

| Prop      | Type   | Default    | Description                                                                             |
| --------- | ------ | ---------- | --------------------------------------------------------------------------------------- |
| icon      | node   |            | Represents the icon to be displayed on the Playhead                                     |
| label     | string | Required   | Label prop for the playhead                                                             |
| onClick   | func   | `() => {}` | Callback that is triggered onClick of the playhead                                      |
| menuItems | array  |            | Array of Menu Components which can be used with the playhead and Variant must be `menu` |
| variant   | string | Required   | Describes is the playhead is one of `button` or `menu`                                  |