player-react

Driift's video player supporting HTML5 video and modern streaming formats, built for use in React. Written in TypeScript, leveraging Video.js, and published via NPM.

Usage

Install

Use your package manager of choice to install the npm package:

npm install @driift/player-react --save

pnpm add @driift/player-react

In practice

In your React application...

import React from 'react'
import { Player } from '@driift/player-react'

function App() {
  // Event handlers

  return (
    <Player
      src="//d2zihajmogu5jn.cloudfront.net/bipbop-advanced/bipbop_16x9_variant.m3u8"
      onMounted={handlePlayerMounted}
      onPlay={handlePlay}
      onPause={handlePause}
      onSeeked={handleSeek}
      onFullscreenChange={handleToggleFullscreen}
      onDispose={handleExit}
    />
  )
}

Component Props

All parameters are optional except src or sources, one of which is required. Video.js determines the default value of most props, although several props are tailored to the Driift experience. Namely:

| Prop Name | Driift Default | | :-------- | :------------- | | autoplay | true | | controls | true | | className | 'vjs-big-play-centered' | | crossorigin | 'anonymous' | | fluid | true | | playsInline | true |

In the table below, "responsive" indicates that Video.js will automatically respond to any updates passed into the given prop, e.g. a change in volume will cause the player to change the volume.

| Prop Name | Video.js API Doc & Description | Type | Responsive | | :---------------------------------------------- | :------------------------------------------------------------------------------------------------- | :--------------------- | :--------- | | id | options.id | String | | | src (required or sources) | options.src | String | ✓ | | sources | options.sources | Array | ✓ | | width | options.width | Number | ✓ | | height | options.height | Number | ✓ | | preload | options.preload | String | ✓ | | loop | options.loop | Boolean | ✓ | | muted | options.muted | Boolean | ✓ | | poster | options.poster | String | ✓ | | controls | options.controls | Boolean | ✓ | | autoplay | options.autoplay | Boolean \| String | ✓ | | playsinline | options.playsinline | Boolean | ✓ | | crossorigin | options.crossOrigin | String | ✓ | | volume | A number, between 0 and 1, control the volume of the player. | Number | ✓ | | playbackRate | Control the playback rate of the player. | Number | ✓ | | playbackRates | options.playbackRates | Array<Number> | ✓ | | fluid | options.fluid | Boolean | ✓ | | fill | options.fill | Boolean | ✓ | | language | options.language | String | ✓ | | languages | options.languages | Object | | | tracks | options.tracks | Array | ✓ | | textTrackSettings | options.textTrackSettings | Object | ✓ | | responsive | options.responsive | Boolean | ✓ | | breakpoints | options.breakpoints | Object | ✓ | | fullscreen | options.fullscreen | FullscreenOptions | | | aspectRatio | options.aspectRatio | Boolean | ✓ | | liveui | options.liveui | Boolean | | | liveTracker | options.liveTracker | Object | | | disablePictureInPicture | options.disablePictureInPicture | Boolean | ✓ | | notSupportedMessage | options.notSupportedMessage | String | ✓ | | normalizeAutoplay | options.normalizeAutoplay | Boolean | ✓ | | audioPosterMode | options.audioPosterMode | Boolean | ✓ | | audioOnlyMode | options.audioOnlyMode | Boolean | ✓ | | noUITitleAttributes | options.noUITitleAttributes | Boolean | | | preferFullWindow | options.preferFullWindow | Boolean | | | suppressNotSupportedError | options.suppressNotSupportedError | Boolean | | | techCanOverridePoster | options.techCanOverridePoster | Boolean | | | techOrder | options.techOrder | Array | | | inactivityTimeout | options.inactivityTimeout | Number | | | userActions | options.userActions | Object | | | restoreEl | options.restoreEl | Boolean \| Element | | | vtt.js | options['vtt.js'] | String | | | videoJsChildren | options.children | Array \| Object | | | html5 | options.html5 | Object | | | plugins | options.plugins | Object | | | options | A fallback scheme, if you need to use options that don't exist in props, pass them to options. | VideoJsPlayerOptions | |

Component Events

Events emitted by Video.js; every event's argument type is always EventTarget.

| Video.js Event | 🫥 🫥 🫥 🫥 🫥 🫥 | Component event | | :----------------------------------------------------------------------------------------- | :---------- | :------------------------ | | event.loadstart | - | onLoadStart | | event.suspend | - | onSuspend | | event.abort | - | onAbort | | event.error | - | onError | | event.emptied | - | onEmptied | | event.stalled | - | onStalled | | event.loadedmetadata | - | onLoadedMetadata | | event.loadeddata | - | onLoadedData | | event.canplay | - | onCanPlay | | event.canplaythrough | - | onCanPlayThrough | | event.playing | - | onPlaying | | event.waiting | - | onWaiting | | event.seeking | - | onSeeking | | event.seeked | - | onSeeked | | event.ended | - | onEnded | | event.durationchange | - | onDurationChange | | event.timeupdate | - | onTimeUpdate | | event.progress | - | onProgress | | event.play | - | onPlay | | event.pause | - | onPause | | event.ratechange | - | onRateChange | | event.resize | - | onResize | | event.volumechange | - | onVolumeChange | | event.posterchange | - | onPosterChange | | event.languagechange | - | onLanguageChange | | event.fullscreenchange | - | onFullscreenChange | | event.playbackrateschange | - | onPlaybackRatesChange | | event.controlsdisabled | - | onControlsDisabled | | event.controlsenabled | - | onControlsEnabled | | event.enterFullWindow | - | onEnterFullWindow | | event.exitFullWindow | - | onExitFullWindow | | event.enterpictureinpicture | - | onEnterPictureInPicture | | event.leavepictureinpicture | - | onLeavePictureInPicture | | event.sourceset | - | onSourceSet | | event.texttrackchange | - | onTextTrackChange | | event.textdata | - | onTextData | | event.useractive | - | onUserActive | | event.userinactive | - | onUserInactive | | event.usingcustomcontrols | - | onUsingCustomControls | | event.usingnativecontrols | - | onUsingNativeControls | | event.dispose | - | onDispose | | event.beforepluginsetup | - | onBeforePluginSetup | | event.pluginsetup | - | onPluginSetup | | event.componentresize | - | onComponentResize | | event.playerresize | - | onPlayerResize | | event.tap | - | onTap | | event.ready | - | onReady |

Events emitted by the @driift/player-react component:

| Component Event | Description | React | | :-------------- | :------------------------------------------------------------------------------------------------------------------------ | :-------------- | | mounted | Fires when player component mounted. ({ video: HTMLVideoElement, player: VideoJsPlayer, state: VideoPlayerState }) | onMounted | | unmounted | Fires when player component unmounted. | onUnmounted | | stateChange | Fires when player state changed. (state: VideoPlayerState) | onStateChange |

Player State

The component maintains a fully responsive state object reflecting the internally state of the Video.js player. This allows you to consume the player state out-of-the-box, outside the player. You can get this object via the mounted or stateChange event.

| Key | Description | Value type | | :------------------- | :------------------------------------------------------------- | :--------------------------------------------------------------------------------- | | src | The URL of the currently playing video. | String | | currentSrc | ditto | String | | currentSource | The currently playing video source object. | videojs.Tech.SourceObject | | width | Player's width. | Number | | height | Player's height. | Number | | currentWidth | ditto | Number | | currentHeight | ditto | Number | | videoWidth | Video element's width. | Number | | videoHeight | Video element's height. | Number | | controls | Whether player controls are enabled or not. | Boolean | | volume | Player's volume. | Number | | muted | Is the player muted. | Boolean | | poster | Player poster image URL. | String | | playing | Is it playing now. | Boolean | | waiting | Is it waiting now. | Boolean | | seeking | A seek operation began. | Boolean | | paused | Playback has been paused. | Boolean | | ended | Playback has stopped because the end of the media was reached. | Boolean | | currentTime | - | Number | | duration | - | Number | | playbackRate | - | Number | | playbackRates | - | Array<Number> | | isFullscreen | - | Boolean | | isInPictureInPicture | Whether it is picture-in-picture mode. | Boolean | | isLive | Is the currently playing live video. | Boolean | | language | Video.js current language. | String | | userActive | - | Boolean | | readyState | - | videojs.ReadyState | | networkState | - | videojs.NetworkState | | error | A Custom MediaError of Video.js. | MediaError \| Null | | buffered | An object that contains ranges of time. | videojs.TimeRange | | bufferedPercent | - | Number | | played | - | TimeRanges | | seekable | - | TimeRanges | | textTracks | - | videojs.TextTrackList | | audioTracks | - | videojs.AudioTrackList | | videoTracks | - | videojs.VidioTrackList |

Questions & troubleshooting

For how-to questions or problems that may involve making changes to the code base, please use GitHub issues or reach out to the Driift engineering team directly.

Contributing

Coming soon...

Development

Soon I say!

Testing

Like...sometime in 2023.

CI-CD

It's happening, really!

Publishing

Automatic via semantic-release...also coming soon.