@clappr/player NPM

Clappr is an extensible media player for the web. Your architecture is projected primarily into plugins, adding low accoupling by design to the project and the possibility to add infinitely features easily.

Clappr uses HTMLVideoElement by default, which guarantees support to many platforms. You have the possibility to extend the default HTML5 playback or the playback interface to create a new media support, just like a plugin!

Clappr is a composition of two other projects: @clappr/core and @clappr/plugins.

The @clappr/core contains the basic functionalities from Clappr (plugin architecture, class abstractions, public interfaces, events handlers and etc) and the @clappr/plugins are the repository where the plugins maintained by the Clappr team lives. More info about those projects into your repositories.

All Clappr projects are written in *.js using the latest features of ECMAScript.

Clappr is under development but production-ready. Feel free to open issues and send pull requests.

:triangular_flag_on_post: Table of Contents

:clapper: Usage

Via script tag:

Add the following script on your HTML:

<head>
  <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@clappr/player@latest/dist/clappr.min.js"></script>
</head>

Now, create the player:

<body>
  <div id="player"></div>
  <script>
    var player = new Clappr.Player({source: "http://your.video/here.mp4", parentId: "#player"});
  </script>
</body>

:video_camera: Demo

Live demo to test, with a possibility to add external plugins.

:books: API Documentation

You can check the current API doc via @clappr/core here.

:hammer_and_wrench: Configuration

You can check the embed parameters supported by @clappr/core here.

:electric_plug: Built-in Plugins

You can check the plugins used on Clappr player via @clappr/plugins here.

:handshake: Third party plugins/integrations

External Plugins

Plugin	Status	Compatible with latest Clappr	URL
Media Control	Ready	Yes	https://github.com/joaopaulovieira/clappr-media-control-plugin
Video Queue (Playlist)	Ready	Yes	https://github.com/joaopaulovieira/clappr-queue-plugin
Thumbnails on seekbar	Ready	Yes	https://github.com/tjenkinson/clappr-thumbnails-plugin
Markers	Ready	Yes	https://github.com/tjenkinson/clappr-markers-plugin
Level Selector	Ready	Yes	https://github.com/clappr/clappr-level-selector-plugin
360 videos	Ready	Yes	https://github.com/thiagopnts/video-360
Chromecast	Ready	Yes	https://github.com/clappr/clappr-chromecast-plugin
DASH with shaka	Ready	Yes	https://github.com/clappr/dash-shaka-playback
Playback Speed	Ready	Yes	https://github.com/bikegriffith/clappr-playback-rate-plugin
Clappr Stats	Ready	Yes	https://github.com/leandromoreira/clappr-stats
Clappr Nerd Stats	Ready	Yes	https://github.com/lucasrodcosta/clappr-nerd-stats
Pause while far	Ready	Yes	https://github.com/leandromoreira/clappr-pause-tab-visibility
RTMP	Ready	Yes	https://github.com/clappr/clappr-rtmp-plugin
Picture-in-Picture	Ready	Yes	https://github.com/tjenkinson/clappr-pip-plugin
Hybrid P2P & CDN	Ready	Yes	https://support.streamroot.io/hc/en-us/articles/360000913654-Clappr
Comments on seekbar	Ready	?	https://github.com/Metrakit/clappr-comment-plugin
Voice control	Ready	?	https://github.com/flavioribeiro/clappr-speech-control-plugin
Dash	WIP	No	https://github.com/shankardevy/clappr-dash-plugin
Youtube	Ready	No	https://github.com/towerz/clappr-youtube-playback
Googel IMA Pre Roll	Ready	Yes	https://github.com/kslimani/clappr-google-ima-html5-preroll
VAST Ad plugin	WIP	No	https://github.com/vix-simplex/clappr-ad-plugin
Dynamic Overlay	Ready	Yes	https://github.com/Lethea/clappr-dynamic-text-overlay
Scroll Text Overlay	Ready	Yes	https://github.com/Lethea/clappr-marquee-overlay
Playback Speed Controller	Ready	Yes	https://github.com/Lethea/clapper-playback-speed-plugin-extended
FLV	Ready	Yes	https://github.com/andrefilimono/clappr-flvjs-playback
Context Menu	Ready	Yes	https://github.com/joaopaulovieira/clappr-context-menu-plugin

External Integrations

Integration	Status	Compatible with latest Clappr	URL
P2P Media Loader	Ready	Yes	https://github.com/Novage/p2p-media-loader

:film_strip: Supported Formats

Format	HLS	MP4	MP3	WEBM	DASH	RTMP	JPG/PNG/GIF	FLV
IE10	✔	✔	✔	✘	✘		✔	✘
IE11	✔	✔	✔	✘			✔
Microsoft Edge	✔	✔	?	?			?
Firefox	✔	✔	✔	✔
Chrome	✔	✔	✔	✔			✔
Safari	✔	✔	✔	✘
iPhone	✔	✔	✔	✘	✘	✘	✔	✘
iPad	✔	✔	✔	✘	✘	✘	✔	✘
Android	✔	✔	✔	✘			✘
WiiU Browser	✔	✔	✘	?			✘	?
PS4 Browser	✔	✔	✘	?			✘	?

rtmp means that the support is made by an external plugin.

:play_or_pause_button: About Autoplay

Clappr has no control over autoplay Browser Policy.

Therefore, we're not able to execute play and unmute actions sequentially in every situation. There are a series of scenarios where the Browser blocks these actions based on it’s own policy.

Each browser has their own different restrictions, and the usual behavior is to activate the sound only after a user interacts with the player.

For more info about the auto play video policy, you can read these docs:

:interrobang: FAQ & Troubleshooting

How to write a plugin?

See the wiki for more info.

How can I disable or override a plugin?

Let's say you want to disable or override a plugin.

Disable a plugin

// let's disable the loading animation (the 'spinner' plugin)
var player = new Clappr.Player({ ... });
// after attach
player.getPlugin('spinner').disable();

Override a plugin

// let's disable the loading animation (the 'spinner' plugin)
export default class NoSpinner extends UIContainerPlugin {
  get name() { return 'spinner' }
}
new Clappr.Player({ plugins: [NoSpinner]})

How can I Log messages with Clappr?

Add this snippet before you instantiate the player Clappr.Log.setLevel(0)

Common steps to verify issues

Very often people open issues related to stream not working, freezing, glitching, stopping, and so on. You can try these steps below, taking notes about the results:

try to run the same example at CDN
check the cors headers at your servers
try to run it on hls.js demo page
try to run it on flashls. demo page
try to run on your page the following source: http://www.streambox.fr/playlists/x36xhzz/x36xhzz.m3u8
try different browsers/OS's to see if the problems remain
try to use a tool to check the health of your stream (both input, ie: RTMP, and segmentation, ie: DASH or HLS): like mediainfo (for instance you could: mediainfo http://www.example.com/my.m3u8, Apple's mediastreamvalidator too, hls-analyzer and etc.

//HLS-Analyzer usage example

pip install m3u8
git clone https://github.com/epiclabs-io/hls-analyzer.git
cd hls-analyzer
python hls-analyzer.py http://www.streambox.fr/playlists/x36xhzz/x36xhzz.m3u8

How to handle player fatal errors?

Player fatal errors can be handled using onError API event.

var player = new Clappr.Player({
  parent: '#myplayer',
  source: 'http://path.to/my/video.mp4',
  events: {
    onError: function(e) {
      // Here the code to handle the error
    }
  }
});

Note: the type of error event object depends on the type of playback component resolved to play the video.

Example

This is a simple example using the no_op playback to display error messages.

You can try the following Javascript code on Clappr demo page:

var playerElement = document.getElementById("player-wrapper");

var r = 3; // Retry attempts

var player = new Clappr.Player({
  // source: 'http://clappr.io/highline.mp4',
  source: 'http://clappr.io/bad_highline.mp4',
  disableErrorScreen: true, // Disable the internal error screen plugin
  height: 360,
  width: 640,
  events: {
    onError: function(e) {
      r--;
      var s = player.options.source;
      // Replace previous line by the following line to simulate successful recovery
      // var s = (r > 2) ? player.options.source : 'http://clappr.io/highline.mp4';
      var t = 10;
      var retry = function() {
        if (t === 0) {
          var o = player.options;
          o.source = s;
          player.configure(o);
          return;
        }
        Clappr.$('#retryCounter').text(t);
        t--;
        setTimeout(retry, 1000);
      };
      player.configure({
        autoPlay: true,
        source: 'playback.error',
        playbackNotSupportedMessage: 'Network fatal error.' + ((r > 0)
            ? ' Retrying in <span id="retryCounter"></span> seconds ...'
            : ' All retry attempts failed'),
      });
      if (r > 0) {
        retry();
      }
    }
  }
});

player.attachTo(playerElement);

Another example

This example uses a custom error container plugin to display error messages.

You can try the following Javascript code on Clappr demo page:

var playerElement = document.getElementById("player-wrapper");

var ErrorPlugin = Clappr.ContainerPlugin.extend({
  name: 'error_plugin',
  background: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAoAAAAFoBAMAAAA1HFdiAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAAG1BMVEX5+fn//wAA//8A/wD/AP//AAAAAP8XFxf///8H5gWfAAAAAWJLR0QIht6VegAAAAd0SU1FB98IBRIsAXmGk48AAAI5SURBVHja7dJBDYBADADBs4AFLGABC1iohbOPhv1BMvu+NLlp10odqTN1pe7Uk5pQ8wMIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECBAgAABAgQIECDA/wKWxzM71T7ZZrfltNnppgACBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAAECBAgQIECAAL8B+ALjSfYzPnmdzgAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxNS0wOC0wNVQxODo0NDowMSswMTowMCL95a4AAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTUtMDgtMDVUMTg6NDQ6MDErMDE6MDBToF0SAAAAAElFTkSuQmCC',
  bindEvents: function() { this.listenTo(this.container, Clappr.Events.CONTAINER_ERROR, this.onError) },
  hide: function() { this._err && this._err.remove() },
  show: function() {
    var $ = Clappr.$
    this.hide();
    var txt = (this.options.errorPlugin && this.options.errorPlugin.text) ? this.options.errorPlugin.text : 'A fatal error occured.';
    this._err = $('<div>')
      .css({
        'position': 'absolute',
        'z-index': '999',
        'width': '100%',
        'height': '100%',
        'background-image': 'url(' + this.background + ')',
        'background-size': 'contain',
        'background-repeat': 'no-repeat',
        'padding-top': '15%',
        'text-align': 'center',
        'font-weight': 'bold',
        'text-shadow': '1px 1px #fff',
      })
      .append($('<h2>')
        .text(txt)
        .css({
          'font-size': '200%',
        }))
      .append($('<p>').html('Retrying in <span class="retry-counter">10</span> seconds ...')
        .css({
          'font-size': '120%',
          'margin': '15px',
        }));
    this.container && this.container.$el.prepend(this._err);
  },
  onError: function(e) {
    if (!this.container) return;
    this.show();
    this.container.getPlugin('click_to_pause').disable();
    var tid, t = 10, retry = function() {
      clearTimeout(tid);
      if (t === 0) {
        this.container.getPlugin('click_to_pause').enable();
        if (this.options.errorPlugin && this.options.errorPlugin.onRetry) {
          this.options.errorPlugin.onRetry(e);
          return;
        } else {
          this.container.stop();
          this.container.play();
          return;
        }
      }
      $('.retry-counter').text(t);
      t--;
      tid = setTimeout(retry, 1000);
    }.bind(this);
    retry();
  }
});

var player = new Clappr.Player({
  disableErrorScreen: true, // Disable the internal error screen plugin
  source: 'http://clappr.io/bad_highline.mp4',
  plugins: [ErrorPlugin],
  errorPlugin: {
    // text: 'My custom error message.',
    onRetry: function(e) {
      // simulate successful recovery
      // or decide here what to do between each retry
      player.configure({
        source: 'http://clappr.io/highline.mp4',
        autoPlay: true,
      });
    }
  },
  height: 360,
  width: 640
});

player.attachTo(playerElement);