API Docs for: 0.2.41
Show:

Player Class

Extends BaseObject
Module: components

Constructor

Player

()

Example:

Using the Player

Add the following script on your HTML:

<head>
  <script type="text/javascript" src="http://cdn.clappr.io/latest/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>

Methods

attachTo

(
  • element
)
Player

You can use this method to attach the player to a given element. You don't need to do this when you specify it during the player instantiation passing the parentId param.

Parameters:

  • element Object

    a given element.

Returns:

Player:

itself

configure

(
  • options
)
Player

enables to configure a player after its creation

Parameters:

  • options Object

    all the options to change in form of a javascript object

Returns:

Player:

itself

constructor

(
  • options
)

Inherited from BaseObject but overwritten in src/components/player.js:101

Player's constructor

You might pass the options object to build the player.

var options = {source: "http://example.com/video.mp4", param1: "val1"};
var player = new Clappr.Player(options);

Parameters:

  • options Object

    Data options to build a player instance

    • [width] Number optional

      player's width default: 640

    • [height] Number optional

      player's height default: 360

    • [parentId] String optional

      the id of the element on the page that the player should be inserted into

    • [parent] Object optional

      a reference to a dom element that the player should be inserted into

    • [source] String optional

      The media source URL, or {source: <>, mimeType: <>}

    • [sources] Object optional

      An array of media source URL's, or an array of {source: <>, mimeType: <>}

    • [autoPlay] Boolean optional

      automatically play after page load default: false

    • [loop] Boolean optional

      automatically replay after it ends default: false

    • [chromeless] Boolean optional

      player acts in chromeless mode default: false

    • [allowUserInteraction] Boolean optional

      whether or not the player should handle click events when in chromeless mode default: false on desktops browsers, true on mobile.

    • [disableKeyboardShortcuts] Boolean optional

      disable keyboard shortcuts. default: false. true if allowUserInteraction is false.

    • [muted] Boolean optional

      start the video muted default: false

    • [mimeType] String optional

      add mimeType: "application/vnd.apple.mpegurl" if you need to use a url without extension.

    • [actualLiveTime] String optional

      show duration and seek time relative to actual time.

    • [actualLiveServerTime] String optional

      specify server time as a string, format: "2015/11/26 06:01:03". This option is meant to be used with actualLiveTime.

    • [persistConfig] Boolean optional

      persist player's settings (volume) through the same domain default: true

    • [preload] String optional

      video will be preloaded according to preload attribute options default: 'metadata'

    • [maxBufferLength] Number optional

      the default behavior for the HLS playback is to keep buffering indefinitely, even on VoD. This replicates the behavior for progressive download, which continues buffering when pausing the video, thus making the video available for playback even on slow networks. To change this behavior use maxBufferLength where value is in seconds.

    • [gaAccount] String optional

      enable Google Analytics events dispatch (play/pause/stop/buffering/etc) by adding your gaAccount

    • [gaTrackerName] String optional

      besides gaAccount you can optionally, pass your favorite trackerName as gaTrackerName

    • [mediacontrol] Object optional

      customize control bar colors, example: mediacontrol: {seekbar: "#E113D3", buttons: "#66B2FF"}

    • [hideMediaControl] Boolean optional

      control media control auto hide default: true

    • [hideVolumeBar] Boolean optional

      when embedded with width less than 320, volume bar will hide. You can force this behavior for all sizes by adding true default: false

    • [watermark] String optional

      put watermark: 'http://url/img.png' on your embed parameters to automatically add watermark on your video. You can customize corner position by defining position parameter. Positions can be bottom-left, bottom-right, top-left and top-right.

    • [watermarkLink] String optional

      watermarkLink: 'http://example.net/' - define URL to open when the watermark is clicked. If not provided watermark will not be clickable.

    • [disableVideoTagContextMenu] Boolean optional

      disables the context menu (right click) on the video element if a HTML5Video playback is used.

    • [autoSeekFromUrl] Boolean optional

      Automatically seek to the seconds provided in the url (e.g example.com?t=100) default: true

    • [exitFullscreenOnEnd] Boolean optional

      Automatically exit full screen when the media finishes. default: true

    • [poster] String optional

      define a poster by adding its address poster: 'http://url/img.png'. It will appear after video embed, disappear on play and go back when user stops the video.

    • [playbackNotSupportedMessage] String optional

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

    • [events] Object optional

      Specify listeners which will be registered with their corresponding player events. E.g. onReady -> "PLAYER_READY", onTimeUpdate -> "PLAYER_TIMEUPDATE"

destroy

() Player

destroys the current player and removes it from the DOM.

Returns:

Player:

itself

getCurrentTime

() Number

the current time in seconds.

Returns:

Number:

current time (in seconds) of the current source

getDuration

() Number

the duration time in seconds.

Returns:

Number:

duration time (in seconds) of the current source

getPlugin

(
  • name
)
Object

get a plugin by its name.

Parameters:

Returns:

Object:

the plugin instance

Example:

var poster = player.getPlugin('poster');
poster.hidePlayButton();

getStartTimeOffset

() Number

The time that "0" now represents relative to when playback started. For a stream with a sliding window this will increase as content is removed from the beginning.

Returns:

Number:

time (in seconds) that time "0" represents.

getVolume

() Number

Get the volume for the current video

Returns:

Number:

volume should be a number between 0 and 100, 0 being mute and 100 the max volume.

isDvrEnabled

() Boolean

returns true if DVR is enable otherwise false.

Returns:

isDvrInUse

() Boolean

returns true if DVR is in use otherwise false.

Returns:

isPlaying

() Boolean

checks if the player is playing.

Returns:

Boolean:

true if the current source is playing, otherwise false

listenTo

(
  • obj
  • name
  • callback
  • context
)

Inherited from Events: src/base/events.js:167

listen to an event indefinitely for a given obj

Parameters:

Example:

this.listenTo(this.core.playback, Events.PLAYBACK_PAUSE, this.callback)

listenToOnce

(
  • obj
  • name
  • callback
  • context
)

Inherited from Events: src/base/events.js:179

listen to an event once for a given obj

Parameters:

Example:

this.listenToOnce(this.core.playback, Events.PLAYBACK_PAUSE, this.callback)

load

(
  • sources
  • mimeType
  • [autoPlay=false]
)
Player

loads a new source.

Parameters:

  • sources Array | String

    source or sources of video. An array item can be a string or {source: <>, mimeType: <>}

  • mimeType String

    a mime type, example: 'application/vnd.apple.mpegurl'

  • [autoPlay=false] Boolean optional

    whether playing should be started immediately

Returns:

Player:

itself

mute

() Player

mutes the current video (source).

Returns:

Player:

itself

off

(
  • name
  • callback
  • context
)

Inherited from Events: src/base/events.js:86

stop listening to an event

Parameters:

on

(
  • name
  • callback
  • context
)

Inherited from Events: src/base/events.js:53

listen to an event indefinitely, if you want to stop you need to call off

Parameters:

once

(
  • name
  • callback
  • context
)

Inherited from Events: src/base/events.js:68

listen to an event only once

Parameters:

pause

() Player

pauses the current video (source).

Returns:

Player:

itself

play

() Player

plays the current video (source).

Returns:

Player:

itself

resize

(
  • size
)
Player

resizes the current player canvas.

Parameters:

  • size Object

    should be a literal object with height and width.

Returns:

Player:

itself

Example:

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

seek

(
  • time
)
Player

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

Parameters:

  • time Number

    should be a number between 0 and the video duration.

Returns:

Player:

itself

seekPercentage

(
  • time
)
Player

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

Parameters:

  • time Number

    should be a number between 0 and 100.

Returns:

Player:

itself

setParentId

(
  • parentId
)
Player

Specify a parentId to the player.

Parameters:

  • parentId String

    the element parent id.

Returns:

Player:

itself

setVolume

(
  • volume
)
Player

Set the volume for the current video (source).

Parameters:

  • volume Number

    should be a number between 0 and 100, 0 being mute and 100 the max volume.

Returns:

Player:

itself

stop

() Player

stops the current video (source).

Returns:

Player:

itself

stopListening

(
  • obj
  • name
  • callback
)

Inherited from Events: src/base/events.js:144

stop listening an event for a given object

Parameters:

trigger

(
  • name
)

Inherited from Events: src/base/events.js:122

triggers an event given its name

Parameters:

unmute

() Player

unmutes the current video (source).

Returns:

Player:

itself

Properties

buffering

Boolean

Determine if the playback is having to buffer in order for playback to be smooth. (i.e if a live stream is playing smoothly, this will be false)

ended

Boolean

Determine if the playback has ended.

eventsMapping

Object

An events map that allows the user to add custom callbacks in player's options.

options

Object

returns the object options

uniqueId

String

a unique id prefixed with 'o', o1, o232

Events

CONTAINER_BITRATE

Inherited from Events: src/base/events.js:507

Fired when the container updates its bitrate

Event Payload:

  • bitrate Object

    Data bitrate object

    • [bandwidth] Number optional

      bitrate bandwidth when it's available

    • [width] Number optional

      playback width (ex: 720, 640, 1080)

    • [height] Number optional

      playback height (ex: 240, 480, 720)

    • [level] Number optional

      playback level when it's available, it could be just a map for width (0 => 240, 1 => 480, 2 => 720)

CONTAINER_HIGHDEFINITIONUPDATE

Inherited from Events: src/base/events.js:606

Fired when container updates its video quality

Event Payload:

  • isHD true Boolean

    when is on HD, false otherwise

CONTAINER_LOADEDMETADATA

Inherited from Events: src/base/events.js:532

Fired when the container loaded its metadata

Event Payload:

  • metadata Object

    Data settings object

    • [duration] Number optional

      the playback duration

    • [data] Object optional

      extra meta data

CONTAINER_MEDIACONTROL_HIDE

Inherited from Events: src/base/events.js:621

Fired when the media control hides

CONTAINER_MEDIACONTROL_SHOW

Inherited from Events: src/base/events.js:615

Fired when the media control shows

CONTAINER_OPTIONS_CHANGE

Inherited from Events: src/base/events.js:631

Fired when the options were changed for the container

CONTAINER_PLAYBACKSTATE

Inherited from Events: src/base/events.js:496

Fired when the container internal state changes

Event Payload:

  • state Object

    Data state object

    • [type] String optional

      the playback type

CONTAINER_PROGRESS

Inherited from Events: src/base/events.js:556

Fired when the container is downloading the media

Event Payload:

  • progress Object

    Data progress object

    • [start] Number optional

      initial downloaded content

    • [current] Number optional

      current dowloaded content

    • [total] Number optional

      total content to be downloaded

CONTAINER_READY

Inherited from Events: src/base/events.js:525

Fired when the container is ready

CONTAINER_SEEK

Inherited from Events: src/base/events.js:579

Fired when the container seeks the video

Event Payload:

  • time Number

    the current time in seconds

CONTAINER_SETTINGSUPDATE

Inherited from Events: src/base/events.js:600

Fired when the container changes any settings (volume, seek and etc)

CONTAINER_STATE_BUFFERFULL

Inherited from Events: src/base/events.js:594

Fired when the container filled the buffer

CONTAINER_STATE_BUFFERING

Inherited from Events: src/base/events.js:588

Fired when container is buffering

CONTAINER_TIMEUPDATE

Inherited from Events: src/base/events.js:544

Fired when the time is updated on container

Event Payload:

  • progress Object

    Data progress object

    • [current] Number optional

      current time

    • [total] Number optional

      total time

CORE_OPTIONS_CHANGE

Inherited from Events: src/base/events.js:475

Fired when the options were changed for the core

CORE_READY

Inherited from Events but overwritten in src/base/events.js:481

Fired after creating containers, when the core is ready

MEDIACONTROL_CONTAINERCHANGED

Inherited from Events: src/base/events.js:686

Fired when the container was changed

MEDIACONTROL_FULLSCREEN

Inherited from Events: src/base/events.js:640

Fired when the player enters/exit on fullscreen

MEDIACONTROL_HIDE

Inherited from Events: src/base/events.js:652

Fired when the media control hides

MEDIACONTROL_MOUSELEAVE_SEEKBAR

Inherited from Events: src/base/events.js:666

Fired when mouse leaves the seekbar

Event Payload:

  • event the Object

    javascript event

MEDIACONTROL_MOUSEMOVE_SEEKBAR

Inherited from Events: src/base/events.js:658

Fired when mouse enters on the seekbar

Event Payload:

  • event the Object

    javascript event

MEDIACONTROL_NOTPLAYING

Inherited from Events: src/base/events.js:680

Fired when the media is not being played

MEDIACONTROL_PLAYING

Inherited from Events: src/base/events.js:674

Fired when the media is being played

MEDIACONTROL_SHOW

Inherited from Events: src/base/events.js:646

Fired when the media control shows

PLAYBACK_BITRATE

Inherited from Events: src/base/events.js:363

Fired when playback updates its bitrate

Event Payload:

  • bitrate Object

    Data bitrate object

    • [bandwidth] Number optional

      bitrate bandwidth when it's available

    • [width] Number optional

      playback width (ex: 720, 640, 1080)

    • [height] Number optional

      playback height (ex: 240, 480, 720)

    • [level] Number optional

      playback level when it's available, it could be just a map for width (0 => 240, 1 => 480, 2 => 720)

PLAYBACK_BUFFERFULL

Inherited from Events: src/base/events.js:326

Fired when the playback has enough in the buffer to be able to play smoothly, after previously being unable to do this.

This corresponds to the playback buffering property being false.

PLAYBACK_BUFFERING

Inherited from Events: src/base/events.js:316

Fired when the playback starts having to buffer because playback can currently not be smooth.

This corresponds to the playback buffering property being true.

PLAYBACK_DVR

Inherited from Events: src/base/events.js:414

Fired when DVR becomes enabled/disabled.

Event Payload:

  • state Boolean

    true if dvr enabled

PLAYBACK_ENDED

Inherited from Events: src/base/events.js:425

Fired when the media for a playback ends.

Event Payload:

  • name String

    the name of the playback

PLAYBACK_ERROR

Inherited from Events: src/base/events.js:460

Fired if an error occurs in the playback.

Event Payload:

  • error Object

    An object containing the error details

  • name String

    Playback name

PLAYBACK_HIGHDEFINITIONUPDATE

Inherited from Events: src/base/events.js:355

Fired when playback updates its video quality

Event Payload:

  • isHD true Boolean

    when is on HD, false otherwise

PLAYBACK_LEVEL_SWITCH_END

Inherited from Events: src/base/events.js:396

Fired when the playback ends the level switch

PLAYBACK_LEVEL_SWITCH_START

Inherited from Events: src/base/events.js:389

Fired when the playback starts to switch level

PLAYBACK_LEVELS_AVAILABLE

Inherited from Events: src/base/events.js:379

Fired when the playback has its levels

Event Payload:

  • levels the Array

    ordered levels, each one with the following format {id: 1, label: '500kbps'} ps: id should be a number >= 0

  • initial the Number

    initial level otherwise -1 (AUTO)

PLAYBACK_LOADEDMETADATA

Inherited from Events: src/base/events.js:343

Fired when playback loaded its metadata

Event Payload:

  • metadata Object

    Data settings object

    • [duration] Number optional

      the playback duration

    • [data] Object optional

      extra meta data

PLAYBACK_PAUSE

Inherited from Events: src/base/events.js:448

Fired when the media for a playback pauses.

PLAYBACK_PLAY

Inherited from Events: src/base/events.js:438

Fired when the media for a playback starts playing. This is not necessarily when the user requests play() The media may have to buffer first. I.e. isPlaying() might return true before this event is fired, because isPlaying() represents the intended state.

PLAYBACK_PLAY_INTENT

Inherited from Events: src/base/events.js:432

Fired when user requests play()

PLAYBACK_PLAYBACKSTATE

Inherited from Events: src/base/events.js:404

Fired when playback internal state changes

Event Payload:

  • state Object

    Data state object

    • [type] String optional

      the playback type

PLAYBACK_PROGRESS

Inherited from Events: src/base/events.js:284

Fired when the playback is downloading the media

Event Payload:

  • progress Object

    Data progress object

    • [start] Number optional

      initial downloaded content

    • [current] Number optional

      current dowloaded content

    • [total] Number optional

      total content to be downloaded

PLAYBACK_READY

Inherited from Events: src/base/events.js:310

Fired when playback is ready

PLAYBACK_SETTINGSUPDATE

Inherited from Events: src/base/events.js:337

Fired when playback changes any settings (volume, seek and etc)

PLAYBACK_STOP

Inherited from Events: src/base/events.js:454

Fired when the media for a playback is stopped.

PLAYBACK_TIMEUPDATE

Inherited from Events: src/base/events.js:298

Fired when the time is updated on playback

Event Payload:

  • progress Object

    Data progress object

    • [current] Number optional

      current time

    • [total] Number optional

      total time

PLAYER_ENDED

Inherited from Events: src/base/events.js:243

Fired when player ends the video

PLAYER_ERROR

Inherited from Events: src/base/events.js:256

Fired when player receives an error

Event Payload:

PLAYER_FULLSCREEN

Inherited from Events: src/base/events.js:218

Fired when player changes its fullscreen state

Event Payload:

  • whether Boolean

    or not the player is on fullscreen mode

PLAYER_PAUSE

Inherited from Events: src/base/events.js:231

Fired when player pauses

PLAYER_PLAY

Inherited from Events: src/base/events.js:225

Fired when player starts to play

PLAYER_READY

Inherited from Events: src/base/events.js:205

Fired when the player is ready on startup

PLAYER_RESIZE

Inherited from Events: src/base/events.js:211

Fired when player resizes

Event Payload:

  • currentSize Object

    an object with the current size

PLAYER_SEEK

Inherited from Events: src/base/events.js:249

Fired when player seeks the video

Event Payload:

  • time Number

    the current time in seconds

PLAYER_STOP

Inherited from Events: src/base/events.js:237

Fired when player stops

PLAYER_TIMEUPDATE

Inherited from Events: src/base/events.js:263

Fired when the time is updated on player

Event Payload:

  • progress Object

    Data progress object

    • [current] Number optional

      current time

    • [total] Number optional

      total time

PLAYER_VOLUMEUPDATE

Inherited from Events: src/base/events.js:275

Fired when player updates its volume

Event Payload:

  • volume Number

    the current volume