---

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