Player Class

Extends BaseObject

Defined in: src/components/player.js:17

Module: components

Constructor

`Player`

()

Defined in src/components/player.js:17

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>

Index
Methods
Properties
Events

Item Index

Methods

`attachTo`

(

element

)

Player

Defined in src/components/player.js:220

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

Defined in src/components/player.js:505

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

`consent`

() Player

Defined in src/components/player.js:371

Gives user consent to playback. Required by mobile device after a click event before Player.load().

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

Defined in src/components/player.js:361

destroys the current player and removes it from the DOM.

Returns:

Player:

itself

`getCurrentTime`

() Number

Defined in src/components/player.js:532

the current time in seconds.

Returns:

Number:

current time (in seconds) of the current source

`getDuration`

() Number

Defined in src/components/player.js:552

the duration time in seconds.

Returns:

Number:

duration time (in seconds) of the current source

`getPlugin`

(

name

)

Object

Defined in src/components/player.js:516

get a plugin by its name.

Parameters:

name String

of the plugin.

Returns:

Object:

the plugin instance

Example:

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

`getStartTimeOffset`

() Number

Defined in src/components/player.js:541

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

Defined in src/components/player.js:447

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

Defined in src/components/player.js:487

returns true if DVR is enable otherwise false.

Returns:

Boolean:

`isDvrInUse`

() Boolean

Defined in src/components/player.js:496

returns true if DVR is in use otherwise false.

Returns:

Boolean:

`isPlaying`

() Boolean

Defined in src/components/player.js:478

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

listen to an event indefinitely for a given obj

Parameters:

obj Object
name String
callback Function
context Object

Example:

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

`listenToOnce`

(

obj
name
callback
context

)

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

listen to an event once for a given obj

Parameters:

obj Object
name String
callback Function
context Object

Example:

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

`load`

(

sources
mimeType
[autoPlay=false]

)

Player

Defined in src/components/player.js:344

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

Defined in src/components/player.js:456

mutes the current video (source).

Returns:

Player:

itself

`off`

(

name
callback
context

)

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

stop listening to an event

Parameters:

name String
callback Function
context Object

`on`

(

name
callback
context

)

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

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

Parameters:

name String
callback Function
context Object

`once`

(

name
callback
context

)

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

listen to an event only once

Parameters:

name String
callback Function
context Object

`pause`

() Player

Defined in src/components/player.js:391

pauses the current video (source).

Returns:

Player:

itself

`play`

() Player

Defined in src/components/player.js:381

plays the current video (source).

Returns:

Player:

itself

`resize`

(

size

)

Player

Defined in src/components/player.js:329

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

Defined in src/components/player.js:412

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

Defined in src/components/player.js:423

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

Defined in src/components/player.js:206

Specify a parentId to the player.

Parameters:

parentId String

the element parent id.

Returns:

Player:

itself

`setVolume`

(

volume

)

Player

Defined in src/components/player.js:434

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

Defined in src/components/player.js:401

stops the current video (source).

Returns:

Player:

itself

`stopListening`

(

obj
name
callback

)

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

stop listening an event for a given object

Parameters:

obj Object
name String
callback Function

`trigger`

(

name

)

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

triggers an event given its name

Parameters:

name String

`unmute`

() Player

Defined in src/components/player.js:467

unmutes the current video (source).

Returns:

Player:

itself

Properties

`buffering`

Boolean

Defined in src/components/player.js:60

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

Defined in src/components/player.js:51

Determine if the playback has ended.

`eventsMapping`

Object

Defined in src/components/player.js:80

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

`options`

Object

Inherited from BaseObject: src/base/base_object.js:15

returns the object options

`uniqueId`

String

Inherited from BaseObject: src/base/base_object.js:31

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

Events

`CONTAINER_BITRATE`

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

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

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

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_LOADEDTEXTTRACK`

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

Fired when a text track is loaded and available on container for display

`CONTAINER_MEDIACONTROL_HIDE`

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

Fired when the media control hides

`CONTAINER_MEDIACONTROL_SHOW`

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

Fired when the media control shows

`CONTAINER_OPTIONS_CHANGE`

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

Fired when the options were changed for the container

`CONTAINER_PLAYBACKSTATE`

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

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

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

Fired when the container is ready

`CONTAINER_SEEK`

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

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

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

`CONTAINER_STATE_BUFFERFULL`

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

Fired when the container filled the buffer

`CONTAINER_STATE_BUFFERING`

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

Fired when container is buffering

`CONTAINER_TIMEUPDATE`

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

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_CONTAINERS_CREATED`

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

Fired when the containers are created

`CORE_FULLSCREEN`

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

Fired when the fullscreen state change

Event Payload:

whether Boolean

or not the player is on fullscreen mode

`CORE_OPTIONS_CHANGE`

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

Fired when the options were changed for the core

`CORE_READY`

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

Fired after creating containers, when the core is ready

`CORE_SCREEN_ORIENTATION_CHANGED`

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

Fired when the screen orientation has changed. This event is trigger only for mobile devices.

Event Payload:

screen Object

An object with screen orientation screen object
- [event] Object optional
  
  window resize event object
- [orientation] String optional
  
  screen orientation (ie: 'landscape' or 'portrait')

`MEDIACONTROL_CONTAINERCHANGED`

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

Fired when the container was changed

`MEDIACONTROL_FULLSCREEN`

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

Fired when the player enters/exit on fullscreen

`MEDIACONTROL_HIDE`

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

Fired when the media control hides

`MEDIACONTROL_MOUSELEAVE_SEEKBAR`

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

Fired when mouse leaves the seekbar

Event Payload:

event the Object

javascript event

`MEDIACONTROL_MOUSEMOVE_SEEKBAR`

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

Fired when mouse enters on the seekbar

Event Payload:

event the Object

javascript event

`MEDIACONTROL_NOTPLAYING`

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

Fired when the media is not being played

`MEDIACONTROL_PLAYING`

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

Fired when the media is being played

`MEDIACONTROL_SHOW`

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

Fired when the media control shows

`PLAYBACK_BITRATE`

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

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

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

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

Fired when DVR becomes enabled/disabled.

Event Payload:

state Boolean

true if dvr enabled

`PLAYBACK_ENDED`

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

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

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

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

Fired when the playback ends the level switch

`PLAYBACK_LEVEL_SWITCH_START`

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

Fired when the playback starts to switch level

`PLAYBACK_LEVELS_AVAILABLE`

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

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

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

Fired when the media for a playback pauses.

`PLAYBACK_PLAY`

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

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

Fired when user requests play()

`PLAYBACK_PLAYBACKSTATE`

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

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

Fired when the playback is downloading the media

Event Payload:

progress Object

Data progress object
- [start] Number optional
  
  start position of buffered content at current position
- [current] Number optional
  
  end position of buffered content at current position
- [total] Number optional
  
  total content to be downloaded
buffered Array

array of buffered segments ({start, end}). [Only for supported playbacks]

`PLAYBACK_READY`

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

Fired when playback is ready

`PLAYBACK_SETTINGSUPDATE`

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

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

`PLAYBACK_STOP`

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

Fired when the media for a playback is stopped.

`PLAYBACK_TIMEUPDATE`

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

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

Fired when player ends the video

`PLAYER_ERROR`

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

Fired when player receives an error

Event Payload:

error Object

the error

`PLAYER_FULLSCREEN`

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

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

Fired when player pauses

`PLAYER_PLAY`

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

Fired when player starts to play

`PLAYER_READY`

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

Fired when the player is ready on startup

`PLAYER_RESIZE`

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

Fired when player resizes

Event Payload:

currentSize Object

an object with the current size

`PLAYER_SEEK`

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

Fired when player seeks the video

Event Payload:

time Number

the current time in seconds

`PLAYER_STOP`

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

Fired when player stops

`PLAYER_TIMEUPDATE`

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

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

Fired when player updates its volume

Event Payload:

volume Number

the current volume

APIs

Player Class

Constructor

Player

Example:

Using the Player

Item Index

Methods

Properties

Events

Methods

attachTo

Parameters:

Returns:

configure

Parameters:

Returns:

consent

Returns:

constructor

Player's constructor

Parameters:

destroy

Returns:

getCurrentTime

Returns:

getDuration

Returns:

getPlugin

Parameters:

Returns:

Example:

getStartTimeOffset

Returns:

getVolume

Returns:

isDvrEnabled

Returns:

isDvrInUse

Returns:

isPlaying

Returns:

listenTo

Parameters:

Example:

listenToOnce

Parameters:

Example:

load

Parameters:

Returns:

mute

Returns:

off

Parameters:

on

Parameters:

once

Parameters:

pause

Returns:

play

Returns:

resize

Parameters:

Returns:

Example:

seek

Parameters:

Returns:

seekPercentage

Parameters:

Returns:

setParentId

Parameters:

Returns:

setVolume

Parameters:

Returns:

stop

`Player`

`attachTo`

`configure`

`consent`

`constructor`

`destroy`

`getCurrentTime`

`getDuration`

`getPlugin`

`getStartTimeOffset`

`getVolume`

`isDvrEnabled`

`isDvrInUse`

`isPlaying`

`listenTo`

`listenToOnce`

`load`

`mute`

`off`

`on`

`once`

`pause`

`play`

`resize`

`seek`

`seekPercentage`

`setParentId`

`setVolume`

`stop`

`stopListening`

`trigger`

`unmute`

`buffering`

`ended`

`eventsMapping`

`options`

`uniqueId`

`CONTAINER_BITRATE`

`CONTAINER_HIGHDEFINITIONUPDATE`

`CONTAINER_LOADEDMETADATA`

`CONTAINER_LOADEDTEXTTRACK`

`CONTAINER_MEDIACONTROL_HIDE`

`CONTAINER_MEDIACONTROL_SHOW`

`CONTAINER_OPTIONS_CHANGE`

`CONTAINER_PLAYBACKSTATE`

`CONTAINER_PROGRESS`

`CONTAINER_READY`

`CONTAINER_SEEK`

`CONTAINER_SETTINGSUPDATE`

`CONTAINER_STATE_BUFFERFULL`

`CONTAINER_STATE_BUFFERING`

`CONTAINER_TIMEUPDATE`

`CORE_CONTAINERS_CREATED`

`CORE_FULLSCREEN`

`CORE_OPTIONS_CHANGE`

`CORE_READY`

`CORE_SCREEN_ORIENTATION_CHANGED`

`MEDIACONTROL_CONTAINERCHANGED`

`MEDIACONTROL_FULLSCREEN`

`MEDIACONTROL_HIDE`

`MEDIACONTROL_MOUSELEAVE_SEEKBAR`

`MEDIACONTROL_MOUSEMOVE_SEEKBAR`

`MEDIACONTROL_NOTPLAYING`

`MEDIACONTROL_PLAYING`

`MEDIACONTROL_SHOW`

`PLAYBACK_BITRATE`

`PLAYBACK_BUFFERFULL`

`PLAYBACK_BUFFERING`

`PLAYBACK_DVR`

`PLAYBACK_ENDED`

`PLAYBACK_ERROR`

`PLAYBACK_HIGHDEFINITIONUPDATE`

`PLAYBACK_LEVEL_SWITCH_END`

`PLAYBACK_LEVEL_SWITCH_START`

`PLAYBACK_LEVELS_AVAILABLE`