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/)
• 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 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 |