Skip to content

cadenzah/videojs-react-enhanced

BranchesTags

Repository files navigation

videojs-react-enhanced

NPM

Build Status codecov

React.js wrapper component for Video.js player with handy and powerful features.

NOTE: The basic feature is working, but still it's currently working in progress, so provided features are unstable and in-depth features are not supported yet, and some usage could change in the future release. Please understand and be careful on using!

Table of Contents

  • Features
  • Install
    • Prerequisite
  • Usage
    • TypeScript Usage
    • Props to initialize player
    • Props to add custom event handlers
    • Plugins
  • Contribution
  • License

Features

  • Easy to use
  • Easy to configure video.js options
    • native HTML5 <video> options, video.js-native options
  • Add custom event handlers for video events
  • Configure Video.js plugins
  • TypeScript support - props, options
  • ...and more features later!
    • CSS Style modification for UI components
    • Adding / Editing UI components

Install

# using npm
npm install --save videojs-react-enhanced
# using yarn
yarn add videojs-react-enhanced

Prerequisite

videojs-react-enhanced uses React and Video.js as peer dependencies. To use this module, you should manually install those dependencies in your project.

# using npm
npm install --save react video.js
# using yarn
yarn add react video.js

Usage

import React from 'react';
import videojs from 'video.js';
import VREPlayer from 'videojs-react-enhanced';
import 'video.js/dist/video-js.css';

function App() {
  const playerOptions = {
    src: 'http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
    controls: true, 
    autoplay: "play",
  };
  const videojsOptions = {
    fluid: true,
  };

  return (
    <VREPlayer
      playerOptions={options}
      videojsOptions={videojsOptions}
      onReady={(player) => console.log(player)}
      onPlay={(e, _, second) => console.log('Play!')}
      onPause={(e, _, second) => console.log('Pause!')}
      onEnded={(e, _) => console.log('Ended!')}
    />
  );
}

export default App;

NOTE: You should import video.js first than videojs-react-enhanced so that videojs object instantiated here is shared with videojs-react-enhanced.

NOTE: You should import video.js/dist/video-js.css after you import videojs-react-enhanced, otherwise the default style of player UI will be all broken. If you are using Next.js for your service, you can remove the statement importing CSS style as that is a global CSS style. See this issue for better understanding.

Typescript Usage

import React from 'react';
import videojs from 'video.js';
import VREPlayer from 'videojs-react-enhanced';
import 'video.js/dist/video-js.css';

function App(): JSX.Element {
  const playerOptions: VREPlayer.IPlayerOptions = {
    src: 'http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
    controls: true, 
    autoplay: "play",
  };
  const videojsOptions: VREPlayer.IVideoJsOptions = {
    fluid: true,
  };

  return (
    <VREPlayer
      playerOptions={options}
      videojsOptions={videojsOptions}
      onReady={(player) => console.log(player)}
      onPlay={(e, _, second) => console.log('Play!')}
      onPause={(e, _, second) => console.log('Pause!')}
      onEnded={(e, _) => console.log('Ended!')}
    />
  );
}

export default App;

You can use TypeScript types from videojs-react-enhanced module.

Props to initialize player

Options to initizliae player are categorized depending on characterisics of each options. There are 4 different options to pass into props: playerOptions, resources, videojsOptions, hideList

You can configure each options and pass it through props as you can see in the Usage section above. Every option can be omitted and default value will be placed in it.

NOTE: If you are using TypeScript in your project, you can utilize Player.PlayerProps type to get information of types you can use

NOTE: See all available options for videojs in official documentation; Currently not every option is supported via this module. If you want other options to be supported which are not on the list below, please make an issue for it!

playerOptions

Options which are standard HTML5 <video> element attributes.

IPlayerOptions type in TypeScript

Option name Datatype Default value Description
autoplay boolean, 'muted', 'play', 'any' false On loaded whether the content will be started automatically or not
control boolean false Whether the player control bar will be shown or not
height number The content's height The player's height
loop boolean false Whether the content will be played again when the playback ends
muted boolean false Whether the content's audio will be muted or not
preload 'auto', 'metadata', 'none' 'auto' The way the content will be loaded.
src string "" The content's URL to load
width number The content's width The player's width

resources

Options to provide multiple content's resources. An array of objects that mirror the native <video> element's capability to have a series of child <source> elements. This should be an array of objects with the src and type properties.

In poster props, you can provide the URL for the content's poster image. This image will be displayed before the content starts playing.

IResources type in TypeScript

// example
const resources = {
  sources: [
    {
      src: 'http://url/to/source',
      type: 'video/type'
    },
    // ...
  ],
  poster: 'http://url/to/poster/image'
}

videojsOptions

Options which are videojs specific.

IVideoJsOptions type in TypeScript

Option name Datatype Default value Description
aspectRatio string Content's original ratio Player's screen ratio
fluid bool false The player's size will fit its container
inactivityTimeout number 0 How many milliseconds of inactivity is required before declaring the user inactive
language string en The player's language
nativeControlsForTouch bool false Whether to enable native controls for touch devices
notSupportedMessage string Default string Override the default message that is displayed when Video.js cannot play back a media source
playbackRates Array<number> undefined List of playback rates available to switch
plugins Array<IVideoJsPlugin [] List of Video.js plugins used for the player (See Plugins section)

hideList

Videojs player displays several UI components as a default, and you can choose what to hide by providing the target UI component's names.

// example
const hideList = [
  'remainingTimeDisplay',
  'playbackRateMenuButton',
]

<Player
  hideList={hideList}
/>

You can hide the components on the list below:

Component name Description
remainingTimeDisplay The text showing the remaining running time
pictureInPictureToggle The button to toggle PIP feature
playbackRateMenuButton The menu button to choose playback rate
playToggle The button to play/pause the content
progressControl The UI to control the content play
volumePanel The menu button to control volume

NOTE: This feature will be renewed after Adding / Editing UI components feature is updated, so please be careful on using it.

Props to add custom event handlers

You can set custom event handlers for standard HTML5 Video events through props as you can see in Usage section above.

NOTE: If you want other events to be supported which are not on the list below, please make an issue for it!

onReady

  • Mapped event: ready
  • Callback arguments:
    No. Arg. name Arg. datatype Description
    1 event EventTarget Information object describing the emitted event
    2 player VideoJsPlayer Videojs Player object from which the event emitted

onPlay

  • Mapped event: play
  • Callback arguments:
    No. Arg. name Arg. datatype Description
    1 event EventTarget Information object describing the emitted event
    2 player VideoJsPlayer Videojs Player object from which the event emitted
    3 currentTimeSecond number The timestamp value when the event occured

onPause

  • Mapped event: pause
  • Callback arguments:
    No. Arg. name Arg. datatype Description
    1 event EventTarget Information object describing the emitted event
    2 player VideoJsPlayer Videojs Player object from which the event emitted
    3 currentTimeSecond number The timestamp value when the event occured

onWaiting

  • Mapped event: waiting
  • Callback arguments:
    No. Arg. name Arg. datatype Description
    1 event EventTarget Information object describing the emitted event
    2 player VideoJsPlayer Videojs Player object from which the event emitted
    3 currentTimeSecond number The timestamp value when the event occured

onTimeUpdate

  • Mapped event: timeupdate
  • Callback arguments:
    No. Arg. name Arg. datatype Description
    1 event EventTarget Information object describing the emitted event
    2 player VideoJsPlayer Videojs Player object from which the event emitted
    3 currentTimeSecond number The timestamp value when the event occured

onSeeking

  • Mapped event: seeking
  • Callback arguments:
    No. Arg. name Arg. datatype Description
    1 event EventTarget Information object describing the emitted event
    2 player VideoJsPlayer Videojs Player object from which the event emitted
    3 currentTimeSecond number The timestamp value when the seeking action started

onSeeked

  • Mapped event: seeked
  • Callback arguments:
    No. Arg. name Arg. datatype Description
    1 event EventTarget Information object describing the emitted event
    2 player VideoJsPlayer Videojs Player object from which the event emitted
    3 startPositionSecond number The timestamp value when the seeking action initially started
    4 completeTimeSecond number The timestamp value when the seeking action finally finished

onEnded

  • Mapped event: ended
  • Callback arguments:
    No. Arg. name Arg. datatype Description
    1 event EventTarget Information object describing the emitted event
    2 player VideoJsPlayer Videojs Player object from which the event emitted

onError

  • Mapped event: error
  • Callback arguments:
    No. Arg. name Arg. datatype Description
    1 event EventTarget Information object describing the emitted event
    2 player VideoJsPlayer Videojs Player object from which the event emitted

onLoadedData

  • Mapped event: ended
  • Callback arguments:
    No. Arg. name Arg. datatype Description
    1 event EventTarget Information object describing the emitted event
    2 player VideoJsPlayer Videojs Player object from which the event emitted

onLoadedMetadata

  • Mapped event: ended
  • Callback arguments:
    No. Arg. name Arg. datatype Description
    1 event EventTarget Information object describing the emitted event
    2 player VideoJsPlayer Videojs Player object from which the event emitted

Plugins

You can apply any plugins and augment your player easily. You can simply list over plugins you want to use in props, and that's it!

import React from 'react';
import videojs from 'video.js';
import '<PLUGIN_YOU_WANT_TO_USE>';
import VREPlayer from 'videojs-react-enhanced';

function App() {
  // ...
  return (
    <VREPlayer
      // ...
      videojsOptions={{
        plugins: [
          {
            name: '<NAME_OF_PLUGIN>',
            options: {
              // ...
            }
          },
          // ...
        ]
      }}
      // ...
    />
  );
}

export default App;

plugins is an array of plugin objects which have properties as below:

No. property name Arg. datatype Description
1 name string The name of plugin (identifier after registration)
2 plugin function The plugin function for manual registration
3 option object The option for plugin

You should include plugins array in videojsOptions and pass it through props.

Depending on the way the plugin executes, there are 2 ways of using plugins, which will be covered right after. You can use both ways together, but just remember that the plugins passed will be handled in the order of plugins array.

Automatic registration and initialization

In some cases, a plugin registers itself on video.js module instance and makes itself available to use by the time it is loaded in the project. Which means, all you have to do is import the plugin and set up an option if exists:

import React from 'react';
import videojs from 'video.js';
import '<PLUGIN_YOU_WANT_TO_USE>';
import VREPlayer from 'videojs-react-enhanced';
// codes to be continued...

When import '<PLUGIN_YOU_WANT_TO_USE>'; line executes, the plugin will locate videojs object in the project and register itself on it. This is important, because you have to import video.js on first, and import the plugin on the next line, so that your plugin uses the video.js module previously loaded, not importing its own video.js inside the plugin.

Also, when you import video.js, it is recommended to import it with the name videojs, as most plugins activates under the assumption that videojs is the name of a variable where video.js module instance is.

All you have to do next is hand over an option object via props if needed:

// continues from the code right above:
function App() {
  // ...

  const videojsOptions = {
    plugins: [
      {
        name: '<NAME_OF_PLUGIN>',
        options: {
          // ...
        },
      },
      // ...
    ]
  }

  return (
    <VREPlayer
      // ...
      videojsOptions={videojsOptions}
      // ...
    />
  );
}

export default App;

NOTE: As official document says, videojs-react-enhanced assumes that a plugin accepts only single option argument to initialize itself.

Keep in mind that there is no plugin property passed in plugin object. That's because the plugin is already loaded and registered by importing '<PLUGIN_YOU_WANT_TO_USE>', so you don't have to specify plugin property. All you have to do is pass the name and an option object for the plugin.

Manual registration and initialization

On the other hand, if you provide plugin in the basic form of function, you need to pass the plugin function through plugin object:

// continues from the code right above:
function myPlugin(player, option) {
  // your plugin's jobs to do...
};

function App() {
  // ...

  const videojsOptions = {
    plugins: [
      {
        name: 'myPlugin',
        plugin: myPlugin,
        options: {
          // ...
        },
      },
      // ...
    ]
  }

  return (
    <VREPlayer
      // ...
      videojsOptions={videojsOptions}
      // ...
    />
  );
}

export default App;

When videojs-react-enhanced gets the passed plugin, it will register the plugin and initialize with the option provided.

NOTE: As official document says, videojs-react-enhanced assumes that a plugin accepts only single option argument to initialize itself.

Contribution

Fork the repository, make changes, commit your work, and make Pull Request.

License

MIT Lisence

About

React.js wrapper component for Video.js player

Topics

react typescript videojs videojs-react-enhanced

Resources

Readme

License

MIT license
Activity

Stars

38 stars

Watchers

5 watching

Forks

12 forks
Report repository

Contributors 2

  •  
  •  

Languages