Clappr-core is part of Clappr player that contains the main architecture of the Clappr project.
Clappr is under development but production-ready. Feel free to open issues and send us pull requests.
Live demo to test with support for external plugins.
- Demo
- Table of Contents
- Features
- Usage
- API Documentation
- Configuration
- Development
- Contributors
- Sponsor
- Uses the HTM5 video tag
- Makes it easy to use while maintaining high platform support.
- Plugin architecture
- Add new features without impacting other functions.
- Extensible
- Add support for other video formats or modify already existing plugins.
Add the following script in your HTML <head>:
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@clappr/core@latest/dist/clappr-core.min.js"></script>Now, create the player by adding the following to your <body>:
<div class="player"></div>
<script>
var playerElement = document.querySelector(".player");
var player = new Clappr.Player({
source: "http://your.video/here.mp4",
parent: playerElement,
});
</script>This project is available on npm at https://www.npmjs.com/package/@clappr/core
yarn install @clappr/core --save-dev
You should specify the base URL for where the assets are located using the baseUrl option:
var player = new Clappr.Player({
source: "http://your.video/here.mp4",
baseUrl: "http://example.com/assets/clappr"
});In the above case, Clappr will expect all of the assets (in the dist folder) to be accessible at "http://example.com/assets/clappr-core".
You need to arrange the assets to be located at baseUrl during your build process.
Installing for webpack:
By default, webpack will look at the main field in package.json and use the built version of the project. If this is all you want, there is nothing else for you to do.
If you would like to build Clappr yourself into your project during your build process then add the following to your webpack config:
resolve: {
alias: { Clappr: '@clappr/core/src/main.js' },
root: [path.resolve(__dirname, 'node_modules/@clappr/core/src')],
extensions: ['', '.js'],
}Installing for browserify:
Browserify will look at the main field in package.json and use the built version of the project.
Create an instance:
var player = new Clappr.Player({
source: "http://your.video/here.mp4",
parentId: "#player"
});
You can use this method to attach the player to a given element. You don't need to do this when specifying it during the player instantiation passing the parentId param.
Plays the current source.
Pauses the current source.
Stops the current source.
Mutes the current source.
Unmutes the current source.
Seeks the current video (source). For example, player.seek(120) will seek to second 120 (2 minutes) of the current video.
Seeks the current video (source). For example, player.seek(50) will seek to the middle of the current video.
Returns true if the current source is playing, otherwise returns false.
Returns the plugin instance. Example:
var strings = player.getPlugin('strings');This method searches the Core and Container plugins by name and returns the first one found.
Returns the current time (in seconds) of the current source.
Returns the duration (in seconds) of the current source.
Resizes the current player canvas. The size parameter should be a literal object with height and width. Example:
player.resize({height: 360, width: 640});Destroy the current player and removes it from the DOM.
Loads a new source.
Enables to configure a player after its creation.
All parameters listed below shall be added on Clappr.Player object instantiation or via player.configure.
Example:
var player = new Clappr.Player({
source: "http://your.video/here.mp4",
parameter1: "value1",
parameter2: "value2",
});
// or
player.configure({
parameter3: "value3",
parameter4: "value4",
})Note that some options passed via configure as not applied instantly. In this case, these options are applied in the next video.
Used to specify where the player should be attached using the DOM element.
Used to specify where the player should be attached using a id of one DOM element.
Sets media source URL to play. You can set the media source accordingly to existing playbacks.
An array of sources. Used to play the next media source on array if the previous one was invalid.
Sets the media source format used on the source option. Use if you need to use a media URL without extension.
Object to add callbacks on mapped events. The current list of mapped events is:
{
events: {
onReady: function() { ... },//Fired when the player is ready on startup
onResize: function() { ... },//Fired when player resizes
onPlay: function() { ... },//Fired when player starts to play
onPause: function() { ... },//Fired when player pauses
onStop: function() { ... },//Fired when player stops
onEnded: function() { ... },//Fired when player ends the video
onSeek: function() { ... },//Fired when player seeks the video
onError: function() { ... },//Fired when player receives an error
onTimeUpdate: function() { ... },//Fired when the time is updated on player
onVolumeUpdate: function() { ... },//Fired when player updates its volume
onSubtitleAvailable: function() { ... },//Fired when subtitles is available
}
}If you want to listen for events from other layers, you need to add the bind for the specific scope.
For example, the CONTAINER_STATE_BUFFERING event is triggered by the container, so if you want to listen for events from the container layer on your code, you can bind events like the example below:
player.core.activeContainer.on(Clappr.Events.CONTAINER_STATE_BUFFERING, function() { ... })See all existing events on Clappr here.
An object used to config external plugins instances and plugins behaviors to Clappr.
{
plugins: {
core: [CorePlugin],
container: [ContainerPlugin],
playback: [Playbacks],
loadExternalPluginsFirst: true,
loadExternalPlaybacksFirst: true,
}
}Example of external plugins config:
// Playback
<script src='https://cdn.jsdelivr.net/npm/@clappr/hlsjs-playback@latest/dist/hlsjs-playback.min.js'></script>
// Container
<script src='https://cdn.jsdelivr.net/npm/@clappr/stats-plugin@latest/dist/clappr-stats.min.js'></script>{
plugins: {
container: [ClapprStats],
playback: [HlsjsPlayback],
}
}You can pass plugins of any category in on flat array too. Example:
{
plugins: [ClapprStats, HlsjsPlayback]
}Default Value:
true
Force external plugins to be loaded before default Clappr plugins.
Default Value:
true
Force external playbacks to be loaded before default Clappr playbacks.
Default Value:
360px
Sets player height. You can set using px (500px) or percentage (100%).
Default Value:
640px
Sets player width. You can set using px (500px) or percentage (100%).
Default Value:
false
Configure Clappr to play media after the player is ready to play.
Default Value:
false
Set volume to zero enabling the video tag muted attribute.
Default Value:
false
Restart video after the video ends enabling the video tag loop attribute.
Default Value:
en-US
Sets one of the current languages supported on Clappr. You can check all supported languages on the Strings plugin.
If you want to provide your translations, create a PR by editing the Strings plugin.
Default Value: The
playback_not_supportedstring on Strings Plugin
Define a custom message to be displayed when playback is not supported.
Default value:
true
Clappr has a pattern to create the code attribute on the error object using the name of the component where an error occurs with the original error code.
Example: hls:networkError_manifestLoadError (component_name:error_code)
You can disable this pattern. Just use the original error code setting this option with the value false.
Default value:
true
By default, if the URL contains a time then the media will seek to this point.
Example: example.com?t=100 would start the media at 100 seconds.
You can disable this behaviour setting this option with the value false.
Default value:
true
By default, Clappr reset a bunch of styles that may impact your own style. With this option, it's possible to enable/disable the use of _resets.scss.
Clappr has a specific set of options for playbacks. The configuration for the playback, it's still only compatible with html5_video playback (and derived playbacks).
Below, the description of each one:
playback: {
preload: 'metadata',
disableContextMenu: false,
controls: true,
crossOrigin: 'use-credentials',
playInline: true,
minimumDvrSize: null,
externalTracks: [],
hlsjsConfig: {},
shakaConfiguration: {},
}Default value:
metadata
In case you're loading an on-demand video (mp4), it's possible to define the way the video will be preloaded according to preload attribute options.
See more about the video tag preload attribute here.
Default value:
false
Disable possibility to activate the context menu.
Default value:
true
Use to enable or disable the HTML5 video tag controls.
Default value:
use-credentials
Use to set one of the possible values supported on the HTML5 video tag.
See more about the video tag crossOrigin attribute here.
Default value:
true
Enable or Disable the HTML5 video tag playInline attribute.
Use to set the minimum value to active DVR for live media. This option is only used for HTML5Playback at this moment.
An array of tracks. Each track must have the attributes src, lang and label. The attribute kind on track object is optional because of the default value subtitles.
See more about tracks on the video tag element here.
Any specific settings for hls.js should be in this option.
{
playback: {
hlsjsConfig: {
// hls.js specific options
}
}
}Any specific settings for shaka-player should be in this option.
{
playback: {
shakaConfiguration: {
// shaka-player specific options
}
}
}Enter the project directory and install the dependencies:
yarn install
Make your changes and run the tests:
yarn test
Build your own version:
yarn build
Check the result on dist/ folder.
Starting a local server:
yarn start
This command will start an HTTP Server on port 8080, you can check a sample page with Clappr on http://localhost:8080/
This project exists thanks to all the people who contribute.
