Wondering what’s next for npm?Check out our public roadmap! »

    videojs-react-enhanced-forked
    TypeScript icon, indicating that this package has built-in type declarations

    0.3.0 • Public • Published

    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

    Install

    npm i videojs-react-enhanced-forked

    DownloadsWeekly Downloads

    1

    Version

    0.3.0

    License

    MIT

    Unpacked Size

    43.9 kB

    Total Files

    19

    Last publish

    Collaborators

    • avatar