Video player API Reference

The Video Player API reference details methods, parameters, and attributes that you can use when working with the videoPlayer object and corresponding <video> tag.

IMPORTANT: The Cloudinary Video Player is currently in Beta and therefore backward compatibility is not guaranteed. We welcome all feedback.

This reference includes:

Video player configuration options
videoPlayer instance methods
Playlist operations
Events

Video Player configuration options

You can define most of the player configuration options either as attributes of the <video> tag or as constructor parameters of the videoPlayer instance. These settings are the default for all videos that play in the Player, but are overridden if a specific video source has a different value for the same setting.

This section includes:

cloudinary.VideoPlayer constructor params
Video tag attributes

For an overview and instructions on setting configuration parameters, see the configuration step of 'Adding a Video Player and video to your page'.

cloudinary.VideoPlayer constructor params

publicId - Cloudinary Public ID of the video source to use when the player loads. You may use this setting for a player that will always play the same video. But in most cases, you will specify the video source Public ID within the videoPlayer.source.
transformation (cloudinary.Transformation, Object, Array or String) - Default transformation to apply on every source video that plays in the player.
posterOptions (Object) - A default poster that is shown every time a new video loads. It can include transformation settings. By default, every new video that loads will use the middle image of that video (/video/publicId.jpg). For example, to set the sample image with a sepia effect as the fixed poster image for all videos:
{ publicId: ‘sample’, effect: [‘sepia’] }
sourceTypes (Array) - The video source types that will be available for the player to request (as appropriate for the current browser) for every video. For HLS and MPEG-DASH, use the values hls and dash respectively. Default: [“mp4”, ”ogg”, “webm”].
sourceTransformation (Object) - Default transformations to apply to a specific source type. For example:
vplayer.sourceTransformation({ ‘mp4’: { width: 410 } })
autoplayMode (String) - The autoplay mode to use for the player. Similar to the default HTML5 autoplay parameter, but with the addition of on-scroll support.
- never - (Default) Disables autoplay.
- always - Enables autoplay.
- on-scroll - Video automatically plays when the majority of the player is inside the viewport, and pauses when the majority of the player is out of view.
playedEventPercents (Array) - An array listing percentage points for which you want to trigger the percentsplayed event. Default: [25, 50, 75, 100].
playedEventTimes (Array) - An array listing times (in seconds) from the beginning of the video for which you want to trigger the timeplayed event. Default: null.
analytics (Boolean) -Whether to activate analytics for video player events. Default: false.
autoplay (Boolean) - Whether to apply standard HTML5 autoplay. Default: false.
loop (Boolean) - Whether to perform standard HTML5 video looping. Default: false.
preload (String) - The type of standard HTML5 video preloading to use. Relevant only when autoplay is false or autoplayMode is never. Default: auto
muted (Boolean) - Whether the player loads in standard HTML5 mute mode. Default: false.
controls (Boolean) - Whether to display the video player controls.

Video tag attributes

Cloudinary attribute parameters are passed as part of the <video> tag in the format data-cld-<configname>. Complex objects are passed as JSON. The attributes listed below have the same descriptions, possible values and defaults as the parallel Javascript parameters listed above.

In addition to the Cloudinary-specific configurations, All HTML5 constructor attributes can be passed as HTML tag attributes as usual.

The following Cloudinary attribute parameters are supported. An example for each is shown:

data-cld-transformation='{ "width": 200, "crop": "limit" }'

data-cld-poster-options='{ "publicId": "sample", "effect": ["sepia"] }'

data-cld-source='{ "publicId": "oceans", "transformation": { "width": 500 } }'

data-cld-source-types='["mp4", "ogg", "webm"]'

data-cld-source-transformation='{ "mp4": { "width": 410 } }'

```
data-cld-public-id="oceans" 
```
```
data-cld-autoplay-mode="on-scroll" 
```

videoPlayer instance methods

The videoPlayer methods below enable you to get or set properties or perform operations on your player after the initial instance loads.

Most of the methods return the player, so you can chain method calls. For example, the following code creates a playlist for the Player and then activates the Play command:

vplayer.playlist(['oceans', 'negative', 'book' ], { autoAdvance: 0 }).play()

vplayer.mute().transformation({ effect: [“sepia”]} ).source(...).play()

Supported methods:

currentPublicId()- Gets the current source’s Cloudinary Public ID.
vplayer.currentPublicId()
source(publicId, options) or source(Options) - Sets a new video source for the player and configures it according to the specified videoSource constructor parameters:
- publicId (String) - The Cloudinary Public ID of the video to play. Can be specified as a standalone parameter or within the options parameter.
- transformation (cloudinary.Transformation, Object, Array or String) - The transformation to apply on the specified video source.
- poster (Object or ImageSource) - The poster to show while the video source is loading. Default: the middle image of the source video (/video/publicId.jpg)
- sourceTypes (Array) - The video source types that will be available for the player to request (as appropriate for the current browser) for this video source. For HLS and MPEG-DASH, use the values hls and dash respectively. Default: [“mp4”, ”ogg”, “webm”].
- sourceTransformation (Hash) - Default transformations to apply to a specific source type. For example:
  vplayer.sourceTransformation({ ‘mp4’: { width: 410 } }) // publicId set in a standalone param vplayer.source(‘oceans’, { transformation: { angle: 45 }, sourceTypes: [“mp4”, “ogg”] }) // publicId set in the options param vplayer.source({ publicId: ‘oceans’, transformation: { angle: 45 }, sourceTypes: [“mp4”, “ogg”] })

posterOptions(options) - Gets or sets the Public ID and/or transformation to apply from now on when a new video loads. By default, every new video that loads uses the middle image of that video (/video/publicId.jpg).

// Apply a sepia effect to each poster
vplayer.posterOptions({ transformation: { effect: [‘sepia’] } })

// Set a fixed poster with a sepia effect to all videos:
vplayer.posterOptions({ publicId: ‘sample’, transformation { effect: [‘sepia’] } })

playlist(sources,{ autoAdvance, repeat }) - Gets or sets a list of video sources to play in the player, including any required transformations.

autoAdvance - Possible values:
- 0 - advance immediately
- Any positive value - delay in seconds between videos
- false - do not advance
repeat - Boolean. Whether to loop back to the first video after the last video in the playlist ends.

You can also change these options and perform many other operations on the playlist instance after the player is created. For details, see: Playlist operations.

// Play video with publicId ‘book’, followed by a video with
// publicId ‘oceans’ and an override transformation, followed
// by a video with a publicId ‘dog’.
// Automatically advance from finished video to the next after
// 10 seconds.
// Restart the playlist from the beginning when finished.

vplayer.playlist([
  ‘book’, 
  { publicId: ‘oceans’, 
    transformation: { width: 500, crop: ‘pad’ } },
  ‘dog’
], autoAdvance: 10, repeat: true)

// Same as before, without any delay between videos and 
// stops after playing the last video.

vplayer.playlist([
  ‘book’, 
  { publicId: ‘oceans’, 
    transformation: { width: 500, crop: ‘pad’ } },
  ‘dog’
], autoAdvance: 0, repeat: false)

playlistByTag(tag,{ sorter, sourceParams, autoAdvance, repeat }) - Performs a call to the client-side resource list operation and returns a promise object that when fulfilled, returns the player with a playlist comprised of all videos in your account with the specified tag.
- sorter - Receives a function that determines the order of the retrieved video sources.
- sourceParams - source settings that will apply to all retrieved videos.
- autoAdvance - Possible values:
  - 0 - advance immediately
  - Any positive value - delay in seconds between videos
  - false - do not advance
- repeat - Boolean. Whether to loop back to the first video after the last video in the playlist ends.
sourcesByTag(tag,{ sorter, sourceParams, autoAdvance, repeat }) - Retrieves the (promise of) the video sources for a specified tag without actually creating the playlist. This method has the same syntax and supports the same options as the playlistByTag.
play() - Plays the current video.
vplayer.play()
pause() - Pauses the current video.
vplayer.pause()
stop() - Stops the current video (Same as Pause + set currentTime to 0).
vplayer.stop()
playNext() - Plays the next video in the playlist.
vplayer.playNext()
playPrevious() - Plays the previous video in the playlist.
vplayer.playPrevious()

transformation(cloudinary.Transformation, Object, Array or String) - Gets or sets the base transformation of the player.

// Sets transformation using cloudinary.Transformation
var trans = new cloudinary.Transformation
trans.width(500).height(600).crop(‘limit’)
vplayer.transformation(trans)

// Sets transformation using a simple Object
vplayer.transformation({ width: 500, height: 600, crop: ‘limit’ })

sourceTypes(Array) - Gets or sets the default source types that will be used for every video. (for mpeg-dash use dash. For HLS use hls)
vplayer.sourceTypes([‘dash’, ‘mp4’])
sourceTransformation(Object) - Sets the default transformation that will be used for all videos of the specified source type.
vplayer.sourceTransformation({ ‘mp4’: { width: 410 } })
To get the transformation set for a particular source type, use:
mp4Tran = sourceTransformation().mp4
duration() - Returns the duration of the currently playing video.
vplayer.duration()
height(dimension) - Gets or sets the video player’s height.
vplayer.height(490)
width(dimension) - Gets or sets the video player’s width.
vplayer.width(430)
volume(volume) - Gets or sets the video player volume level. The volume is a value between 0 (muted) and 1 (max volume).
vplayer.volume(0.75)
mute() - Mutes the video player.
vplayer.mute()
unmute() - Unmutes the video player and reverts the previous volume level.
vplayer.unmute()
isMuted() - Returns whether player is currently muted.
vplayer.isMuted()
currentTime(offsetSeconds) - Gets or sets the current time of the video that is playing.
// Seek to the beginning of the video vplayer.currentTime(0)
maximize() - Enter fullscreen mode.
vplayer.maximize()
exitMaximize() - Exit fullscreen mode.
vplayer.exitMaximize()
isMaximized() - Returns whether video player is in full screen.
vplayer.isMaximized()
dispose() - Disposes video player and removes its element from the DOM.
el() - Returns the video player DOM element.

on(event, callback) - Registers an event handler to the specified event.

var handler = function (event) {
  console.log(event.eventData.percent + “ percents played”)
}

vplayer.on(‘percentsplayed’, handler)

off(event, callback) - Unregister an event handler from the specified event.
vplayer.off(‘percentsplayed’, handler) ```javascript

Playlist operations

You can create a playlist for your player based on a list of public IDs or for all videos with a specified tag. Use the methods below to control your playlist.

For an overview and instructions on creating a playlist, see Creating a playlist

playAtIndex(index) - Sets the player’s current video source as the one located at the specified 0-based index location in the playlist and starts playing it.
currentIndex(index) - Gets or sets the current video source 0-based index value.
currentSource() - Gets the currently playing videoSource.
list() - Gets an array of videoSource instances for the playlist.
repeat(repeat) - Gets or sets whether the playlist will replay the playlist from the beginning after the last video finishes playing.
playFirst() - Sets the player’s current video source to the first video source in the playlist and plays it.
playLast() - Sets the player’s current video source to the last in the playlist and plays it.
length() - Returns the number of video sources in the playlist.
playNext() - Sets the player’s current source to the next source in the playlist and plays it. If the currently playing source is the last one in the list and repeat is set to true, the first source in the list plays. Otherwise, nothing happens.
playPrevious() - Sets the player’s current source to the previous source in the playlist and plays it. If the currently playing source is the first one in the list, nothing happens.
player() - returns the videoPlayer for this playlist.
autoAdvance(delay) - Gets or sets the autoAdvance configuration for the playlist.
- A positive integer delay value sets the delay in seconds that the player will wait before playing the next video.
- A value of false cancels auto advance. (To move to the next video use playNext).
- A value of 0 causes the next video to play immediately after the previous one finishes.

Events

You can register to video player events and then use these events to create custom video player controls or to trigger other custom behaviors in your application.

Additionally, some of these events can be tracked for Google Analytics or other analytics trackers.

For an overview and instructions on working with video player events, see Using video events
For information on tracking analytics data using events, see Capturing analytics data.

You can register event handlers to the following standard HTML5 Video events:

loadstart, suspend, abort, error, emptied, stalled, loadedmetadata, loadeddata, canplay, canplaythrough, playing, waiting, seeking, seeked, ended, durationchange, timeupdate, progress, play, pause, ratechange, volumechange, fullscreenchange, posterchange.

Additionally, the following events are also available for the Cloudinary Video Player:

mute - Emitted when player is muted.
unmute - Emitted when player is unmuted.

percentsplayed - Emitted when video playback reaches X percent out of the total video duration. The percents that trigger this event defined by the video player constructor’s playedEventPercents parameter.

var vplayer = cld.videoPlayer(“my-video”, { playedEventPercents: [10, 50, 90] })

vplayer.on(‘percentsplayed’, (event) => {
  console.log(event.eventData.percent + “ percents played”) 
})

timeplayed - Emitted when video playback reaches X seconds after the beginning of the video. Seconds are defined by the video player constructor’s playedEventTimes parameter.

var vplayer = cld.videoPlayer(“my-video”, { playedEventTimes: [60, 120, 180] })

vplayer.on(‘timeplayed’, (event) => {
  console.log(event.eventData.time + “ seconds played”) 
})

seek - Emits seekStart and seekEnd data.

vplayer.on(‘seek’, (event) => {
  console.log(“Start: “ + event.eventData.seekStart + “ End: ” + event.eventData.seekEnd) 
})

sourcechanged - Emitted when the video player source changes.