@guzzj/clappr-core

v0.4.20

Published

3 years ago

Core components of the extensible media player for the web

Downloads

0High
0Medium
0Low

guzz-junqueira

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.

:video_camera: Demo

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

:triangular_flag_on_post: Table of Contents

:gem: Features

Based on the HTM5 video tag
- Adding large platforms support and facility to use.
Plugin architecture
- Add new features without impact other's functionalities.
Extensible
- Add support to video formats or modify existing plugins, just extending them.

:clapper: Usage

Via script tag:

Add the following script on your HTML:

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

Now, create the player:

<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>
</body>

Via npm module:

The project is on npm at https://www.npmjs.com/package/@guzzj/clappr-core

yarn install @guzzj/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: '@guzzj/clappr-core/src/main.js' },
    root: [path.resolve(__dirname, 'node_modules/@guzzj/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.

:books: API Documentation

Create an instance:

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

player.attachTo(element)

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.

player.play()

Plays the current source.

player.pause()

Pauses the current source.

player.stop()

Stops the current source.

player.mute()

Mutes the current source.

player.unmute()

Unmutes the current source.

player.seek(value)

Seeks the current video (source). For example, player.seek(120) will seek to second 120 (2 minutes) of the current video.

player.seekPercentage(value)

Seeks the current video (source). For example, player.seek(50) will seek to the middle of the current video.

player.isPlaying()

Returns true if the current source is playing, otherwise returns false.

player.getPlugin(pluginName)

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.

player.getCurrentTime()

Returns the current time (in seconds) of the current source.

player.getDuration()

Returns the duration (in seconds) of the current source.

player.resize(size)

Resizes the current player canvas. The size parameter should be a literal object with height and width. Example:

player.resize({height: 360, width: 640});

player.destroy()

Destroy the current player and removes it from the DOM.

player.load(source)

Loads a new source.

player.configure(options)

Enables to configure a player after its creation.

:hammer_and_wrench: Configuration

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.

Player Configuration

parent

Used to specify where the player should be attached using the DOM element.

parentId

Used to specify where the player should be attached using a id of one DOM element.

source

Sets media source URL to play. You can set the media source accordingly to existing playbacks.

sources

An array of sources. Used to play the next media source on array if the previous one was invalid.

mimeType

Sets the media source format used on the source option. Use if you need to use a media URL without extension.

events

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.

plugins

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]
}

plugins.loadExternalPluginsFirst

Default Value: true

Force external plugins to be loaded before default Clappr plugins.

plugins.loadExternalPlaybacksFirst

Default Value: true

Force external playbacks to be loaded before default Clappr playbacks.

height

Default Value: 360px

Sets player height. You can set using px (500px) or percentage (100%).

width

Default Value: 640px

Sets player width. You can set using px (500px) or percentage (100%).

autoPlay

Default Value: false

Configure Clappr to play media after the player is ready to play.

mute

Default Value: false

Set volume to zero enabling the video tag muted attribute.

loop

Default Value: false

Restart video after the video ends enabling the video tag loop attribute.

language

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.

playbackNotSupportedMessage

Default Value: The playback_not_supported string on Strings Plugin

Define a custom message to be displayed when playback is not supported.

useCodePrefix

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.

autoSeekFromUrl

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.

includeResetStyle

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.

Playback Configuration

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: {},
}

preload

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.

disableContextMenu

Default value: false

Disable possibility to activate the context menu.

controls

Default value: true

Use to enable or disable the HTML5 video tag controls.

crossOrigin

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.

playInline

Default value: true

Enable or Disable the HTML5 video tag playInline attribute.

minimumDvrSize

Use to set the minimum value to active DVR for live media. This option is only used for HTML5Playback at this moment.

externalTracks

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.

hlsjsConfig

Any specific settings for hls.js should be in this option.

{
  playback: {
    hlsjsConfig: {
      // hls.js specific options
    }
  }
}

shakaConfiguration

Any specific settings for shaka-player should be in this option.

{
  playback: {
    shakaConfiguration: {
      // shaka-player specific options
    }
  }
}

:computer: Development

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/

:raised_hands: Contributors

This project exists thanks to all the people who contribute.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

:video_camera: Demo

:triangular_flag_on_post: Table of Contents

:gem: Features

:clapper: Usage

Via script tag:

Via npm module:

Installing for webpack:

Installing for browserify:

:books: API Documentation

player.attachTo(element)

player.play()

player.pause()

player.stop()

player.mute()

player.unmute()

player.seek(value)

player.seekPercentage(value)

player.isPlaying()

player.getPlugin(pluginName)

player.getCurrentTime()

player.getDuration()

player.resize(size)

player.destroy()

player.load(source)

player.configure(options)

:hammer_and_wrench: Configuration

Player Configuration

parent

parentId

source

sources

mimeType

events

plugins

plugins.loadExternalPluginsFirst

plugins.loadExternalPlaybacksFirst

height

width

autoPlay

mute

loop

language

playbackNotSupportedMessage

useCodePrefix

autoSeekFromUrl

includeResetStyle

Playback Configuration

preload

disableContextMenu

controls

crossOrigin

playInline

minimumDvrSize

externalTracks

hlsjsConfig

shakaConfiguration

:computer: Development

:raised_hands: Contributors

:money_with_wings: Sponsor