clappr

by clappr

clappr / clappr

:clapper: An extensible media player for the web.

5.1K Stars 716 Forks Last release: about 1 month ago (0.4.1) BSD 3-Clause "New" or "Revised" License 4.2K Commits 247 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Huge changes in the latest version. See 0.4.0 version changelog for more information

jsDelivr hits (npm scoped)


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 by default the HTMLVideoElement which guarantees support to many platforms. You have the possibility to extends the default HTML5 playback or the playback interface to create one 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.

:triangularflagon_post: Table of Contents

:clapper: Usage

Via script tag:

Add the following script on your HTML:

html

  

Now, create the player:

html

  

: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.

:hammerandwrench: 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| |-----------------------|--------|-------------------------------|--------------------------------------------------------| |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 |

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 rtmp
IE11 rtmp rtmp rtmp
Microsoft Edge ? ? rtmp rtmp ? rtmp
Firefox rtmp rtmp rtmp rtmp
Chrome rtmp rtmp rtmp
Safari rtmp rtmp rtmp rtmp
iPhone
iPad
Android rtmp rtmp rtmp
WiiU Browser ? rtmp rtmp ?
PS4 Browser ? rtmp rtmp ?

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

: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 use clappr with ReactJS?

https://medium.com/@bikegriffith/using-clappr-with-reactjs-14a338e3451f#.9a36w0dpj

How can I use clappr with ionic/angular?

https://github.com/clappr/clappr/issues/933#issuecomment-228540381

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 the 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 the 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 seconds ...' : ' All retry attempts failed'), }); if (r > 0) { retry(); } } } });

player.attachTo(playerElement);

Another example

This example use 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 = $('

') .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($('

') .text(txt) .css({ 'font-size': '200%', })) .append($('

').html('Retrying in 10 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);

:rocket: Companies using Clappr

https://github.com/clappr/clappr/issues/522

:raised_hands: Contributors

This project exists thanks to all the people who contribute.

:star2: Sponsor

image

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.