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.

Configuration options

You can define many of the player configuration options either as attributes of the <video> tag or as constructor parameters of the videoPlayer method. 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:

For an overview and instructions on setting configuration parameters, see the configuration step of 'How to embed the video player'.

Constructor parameters

Use constructor parameters of the videoPlayer method to define global configuration options. You can control:

Player visuals

Param Type Description
colors Object The colors to use for the player UI. The values must be supplied as hex color codes. You can set:
- base: The base color for the player's controls and information bars as well as the base color of the central play button.
- accent: The color for the progress bar and volume level.
- text: The color for all text and icons.
controls Boolean Whether to display the video player controls.
floatingWhenNotVisible FloatingWhenNotVisible Whether to display a floating player in the corner of the screen when a video is playing and less than half the player is visible.
Possible values:
- right: Shows floating player in the bottom right of the screen
- left: Shows floating player in the bottom left of the screen
fluid Boolean Whether to activate fluid layout mode, which dynamically adjusts the player size to fit its container or window.

Note: You can alternatively pass cld-fluid as a css class of the video tag. For example:
class="cld-video-player cld-video-player-skin-dark cld-fluid"

fontFace FontFace The font to use for text elements in the video player. If not specified, the player loads with the default player font-family: Fira Sans.
hideContextMenu Boolean Whether to hide the context menu that appears when right-clicking on the player. Default: false
playlistWidget PlaylistWidgetProps Adds a playlist widget to the video 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: posterOptions{ publicId: 'sample', effect: ['sepia'] }
showJumpControls Boolean Whether to show jump control buttons, allowing the user to skip forward or back 10 seconds.
showLogo Boolean Whether to show a clickable logo within the player. You can customize the logo image (logoImageUrl) and logo url (logoOnclickUrl) for your own requirements. Default: true
logoImageUrl String The URL for the logo image to display in the player's control bar. Relevant only when showLogo is true. Default: Cloudinary logo.
logoOnclickUrl String he URL where the viewer will be sent when clicking the logo in the player control bar. Relevant only when showLogo is true. Default: https://cloudinary.com
videoJS Object Enables you to access all underlying capabilities of the VideoJS API. For details, see the VideoJS Player API.

Player behavior

Param Type Description
autoplay Boolean Whether to apply standard HTML5 autoplay. Default: false.
autoplayMode AutoplayMode The autoplay mode to use for the player. Similar to the default HTML5 autoplay parameter, but with the addition of on-scroll support. Default: never.
autoShowRecommendations Boolean Whether to show recommendations at the end of the current video, if available. For playlists where autoAdvance is false, the next videos are automatically used as the recommendations, if none are explicitly defined. For players with a single source, in addition to setting autoShowRecommendations to true, you must explicitly define the videos to recommend using the source.recommendations parameter. You can also optionally use the source.recommendations parameter for sources in a playlist, which overrides the default behavior of showing the next videos as recommendations.
loop Boolean Whether to perform standard HTML5 video looping. Default: false.
maxTries Number The maximum number of times the video player will attempt to request a video. Multiple requests may be necessary if the video is still being processed when it is first requested. Default = 3. Can be used in conjunction with videoTimeout.
muted Boolean Whether the player loads in standard HTML5 mute mode. Default: false.
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.
videoTimeout Milliseconds The maximum time the video player will wait for a video to be available in each video request. This may be relevant if the video is still being processed when it is first requested. Default = 55000. Can be used in conjunction with maxTries.

Video config

Param Type Description
preload String The type of standard HTML5 video preloading to use. Relevant only when autoplay is false or autoplayMode is never.
Possible values:
- auto: Default. Begin loading the video immediately.
-metadata: Only load the video metadata.
- none: Don't load any video data.
publicID String The Cloudinary Public ID of the video source to use when the player loads. You can use this setting for a player that will always play the same video. But in most cases, it's a better practice to specify the video source Public ID within the videoPlayer.source
sourceTransformation Object Default transformations to apply to a specific source type.
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"].
transformation cloudinary.Transformation, Object, Array or String Default transformation to apply on every source video that plays in the player.

Ads and analytics

Param Type Description
ads AdsProps Enables serving ads in your video player based on leading video ad standards such as VAST, VPAID, and VMAP, including Google DoubleClick or AdSense. For more details, see Video ads and monetization.
analytics Boolean Whether to activate analytics for video player events. Default: false.
allowUsageReport Boolean Cloudinary can optionally collect aggregated statistics about how the video player is being used. The collected data is used in aggregate form to help us improve future versions of the video player and cannot be used to identify individual video viewers. When true (default), Cloudinary collects data on events performed by the video player.

Constructor types

AdsProps

Param Type Description
adTagUrl String Required. The full URL of the adTag to run.
adsInPlaylist AdsInPlaylist Optional. When to call the adTag within a playlist. Default: first-video
showCountdown Boolean Optional. When true, the 'Advertisement' countdown label is displayed in small text in the bottom center of the video player along with a counter showing the time (in seconds) until the end of the video. Default: true.
adLabel String Optional. Alternative or translated text for the 'Advertisement' countdown label. Relevant only when showCountdown is true.
locale String Optional. Locale for ad localization. Can be any ISO 639-1 (two-letter) or ISO 639-2,(three-letter) locale code. This setting affects the language of relevant elements within the adTag, such as the Skip option. Default: en.
prerollTimeout Number Optional. Maximum time (in milliseconds) to wait for a preroll ad to start. If the ad does not start an adtimeout event is triggered.
postrollTimeout Number Optional. Maximum time (in milliseconds) to wait for a postroll ad to start. If the ad does not start an adtimeout event is triggered.

PlaylistWidgetProps

Param Type Description
direction Direction Controls the placement and direction of the widget in web display. In responsive/mobile view, the widget always adjusts to a single column vertical scrolling list below the player. Default: vertical
total String The total number of next videos to include in the widget. A maximum of four thumbnails can be displayed at once. If a larger number is specified for total, the widget scrolls to show the rest.

Constructor enums


AutoplayMode

A string value setting the autoplay mode.

Value Description
never 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.

FloatingWhenNotVisible

A string value setting the location of the floating player.

Value Description
left Shows floating player in the bottom left of the screen.
right Shows floating player in the bottom right of the screen.

FontFace

A string value setting the font face to use for the text elements of the player.

Value Description
<Google Font Name> Loads and uses the specified Google Font.
These fonts are supported on most modern browsers and mobile devices. For more details, see the Google Font FAQ
inherit Inherits the fonts being used on the current web page.
false Applies the default videoJS font family as set via CSS.

AdsInPlaylist

A string value setting when to call the adTag.

Value Description
first-video Calls the adTag on the first video in the playlist only.
every-video Calls the adTag on every video in the playlist.

Direction

A string value setting the direction for upcoming videos.

Value Description
horizontal Displays the thumbnails of upcoming videos horizontally. The widget is located below the player and is in addition to the dimensions defined for the player.
vertical Displays the thumbnails of upcoming videos horizontally. The widget is located to the right of the player and is displayed inside the dimensions defined for the player (the video is resized accordingly).

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 video player constructor 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": "mymovie", "transformation": { "width": 500 } }'
  • data-cld-source-types='["mp4", "ogg", "webm"]'
  • data-cld-source-transformation='{ "mp4": { "width": 410 } }'
  • data-cld-public-id="mymovie" 
  • data-cld-autoplay-mode="on-scroll" 
  • data-cld-floating-when-not-visible="left"
  • data-cld-font-face="Yatra One" 
  • data-cld-colors="{ "base": "#eef9ee", "accent": "#00e64c", "text": "#009688" }" 

Instance methods

The video player 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 instance, so you can chain method calls.

For example, the following code creates a playlist for the player and then calls the play method:

Copy to clipboard
vplayer.playlist(['mymovie', 'movie2', 'movie3' ], { autoAdvance: 0 }).play()

And this code mutes the player, sets a transformation that applies to all sources in that player, sets the source video for the player and then calls the play method:

Copy to clipboard
vplayer.mute().transformation({ effect: ["sepia"]} ).source(...).play()

You can use the instance methods for:

  • Video configuration - configure the video source, playlists and transformations.
  • Controls - handle basic video controls such as playing, pausing and adjusting the volume.
  • Video player element - configure the video player element itself.

Video configuration

currentPublicId

currentPublicId()

Use the currentPublicId method to get the current source’s Cloudinary Public ID.

Copy to clipboard
vplayer.currentPublicId()

source

source(publicId,options)

Use the source method to set a new video source for the player and configure it. Configure the new videoSource using the following as constructor parameters. You can also get or set these as properties or operations on your videoSource object after the initial instance loads.

publicId

The Cloudinary Public ID of the video to play. Can be specified as a standalone parameter or within the options parameter.

Copy to clipboard
// publicId set in a standalone param
vplayer.source('mymovie', { transformation: { angle: 45 }, sourceTypes: ["mp4", "ogg"] })

// publicId set in the options param
vplayer.source({ publicId: 'mymovie', transformation: { angle: 45 }, 
    sourceTypes: ["mp4", "ogg"] })
options
Param Type Description
info Object Optional. The title, subtitle, and description of the video. Used in the main player view, upcoming video for playlists, and the recommendations pane. For example: vplayer.source('mymovie', {info: { title: 'My Title', subtitle: 'Something about the video', description: 'More detail about the video' } })
maxTries Integer The maximum number of times the video player will attempt to request a video. Multiple requests may be necessary if the video is still being processed when it is first requested. Default = 3. Can be used in conjunction with videoTimeout
poster Object The poster to show while the video source is loading. Default: the middle image of the source video (/video/publicId.jpg)
textTracks Object The text tracks to add to the video source, used to add subtitles or captions. For example: player.source('outdoors', {textTracks: { captions: { label: 'English captions', language: 'en', default: true, url: 'https://res.cloudinary.com/demo/raw/upload/outdoors.vtt'} } })
recommendations Array, Function, or Promise The videoSource objects to be shown as recommendations for the current videoSource. Can be specified as an array of sources, or a function or Promise that resolves into an array of sources. See showing video recommendations for more.
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 Object Default transformations to apply to a specific source type. For example: vplayer.source('mymovie'), {sourceTransformation({ 'mp4': { width: 410 }}}). See sourceTransformation method for syntax.
transformation cloudinary.Transformation, Object, Array or String The transformation to apply on the specified video source. See transformation method for syntax.
videoTimeout Integer The maximum time (in milliseconds) that the video player will wait for a video to be available in each video request. This may be relevant if the video is still being processed when it is first requested. Default = 55000. Can be used in conjunction with maxTries.

playlist

playlist(sources,options)

Use the playlist method to get or set a list of video sources to play in the player, including any required transformations.

sources

The video sources to play in the playlist, see source for more information.

options
Param Type Description
autoAdvance Number or false Whether to auto-advance to the next video and the delay between them.
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.
presentUpcoming Boolean Whether to display a thumbnail link of the next video in the list when the current video is almost finished.
Possible values:
- false: Default. Do not present upcoming videos.
- true: Present upcoming videos 10 seconds before the end of the current video.
- Any positive value - Seconds before the end of the current video to show the upcoming video.

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.

Copy to clipboard
// Play video with publicId 'movie2', followed by a video with
// publicId 'mymovie' and an override transformation, followed
// by a video with a publicId 'movie3'.
// Automatically advance from finished video to the next after
// 10 seconds.
// Restart the playlist from the beginning when finished.

vplayer.playlist([
    'movie2', 
    { publicId: 'mymovie', 
        transformation: { width: 500, crop: 'pad' } },
    'movie3'
], autoAdvance: 10, repeat: true)

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

vplayer.playlist([
    'movie2', 
    { publicId: 'mymovie', 
        transformation: { width: 500, crop: 'pad' } },
    'movie3'
], autoAdvance: 0, repeat: false)

playlistByTag

playlistByTag(tag,options)

Use the playlistByTag method to perform a call to the client-side resource list operation and return a promise object that when fulfilled, returns the player with a playlist comprised of all videos in your account with the specified tag.

tag

String value representing the tag name with which to build the playlist from.

options
Param Type Description
sorter Function By default, the video list is sorted in the order returned by Cloudinary. This parameter receives a function that sets the order of the retrieved video sources. Your function should receive two entries and determine which one comes first. This sorter behavior works similarly to the Javascript array CompareFunction.
sourceParams Object Source settings that will apply to all retrieved videos.
autoAdvance Number or false Whether to auto-advance to the next video and the delay between them.
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.
presentUpcoming Boolean Whether to display a thumbnail link of the next video in the list when the current video is almost finished.
Possible values:
- false: Default. Do not present upcoming videos.
- true: Present upcoming videos 10 seconds before the end of the current video.
- Any positive value - Seconds before the end of the current video to show the upcoming video.

sourcesByTag

sourcesByTag(tag,options)

Use the sourcesByTag method to retrieve 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.


autoShowRecommendations

autoShowRecommendations(Boolean)

Use the autoShowRecommendations boolean method to determine whether to show recommendations at the end of the current video, if available. For playlists where autoAdvance is false, the next videos are automatically used as the recommendations, if none are explicitly defined. For players with a single source, in addition to setting autoShowRecommendations to true, you must explicitly define the videos to recommend (or provide a function or Promise that returns and array of sources) using the source.recommendations parameter. You can also optionally use the source.recommendations parameter for sources in a playlist, which overrides the default behavior of showing the next videos as recommendations.


sourceTypes

sourceTypes(Array)

Use the sourceTypes method to get or set the default source types that will be used for every video. (for mpeg-dash use dash. For HLS use hls)

Copy to clipboard
vplayer.sourceTypes(['dash', 'mp4'])

sourceTransformation

sourceTransformation(Object)

Use the sourceTransformation method to set the default transformation that will be used for all videos of the specified source type.

Copy to clipboard
vplayer.sourceTransformation({ 'mp4': { width: 410 } })

To get the transformation set for a particular source type, use:

Copy to clipboard
mp4Tran = sourceTransformation().mp4

transformation

transformation(cloudinary.Transformation, Object, Array or String)

Use the transformation method to get or set the base transformation of the player.

Copy to clipboard
// 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' })

posterOptions

posterOptions(options)

Use the posterOptions method to get or set 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).

options
Param Type Description
publicId string The Public ID of the image to use as the poster.
transformation cloudinary.Transformation, Object, Array or String The transformation to apply on the specified video source. See transformation method for syntax
Copy to clipboard
// 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'] } })

Controls

play

play()

Use the play method to play the current video.

Copy to clipboard
vplayer.play()

pause

pause()

Use the pause method to pause the current video.

Copy to clipboard
vplayer.pause()

stop

stop()

Use the stop method to stop the current video (Same as Pause + set currentTime to 0).

Copy to clipboard
vplayer.stop()

playNext

playNext()

Use the playNext method to play the next video in the playlist.

Copy to clipboard
vplayer.playNext()

playPrevious

playPrevious()

Use the playPrevious method to play the previous video in the playlist.

Copy to clipboard
vplayer.playPrevious()

volume

volume(volume)

Use the volume method to get or set the video player volume level. The volume is a value between 0 (muted) and 1 (max volume).

Copy to clipboard
vplayer.volume(0.75)

mute

mute()

Use the mute method to mute the video player.

Copy to clipboard
vplayer.mute()

unmute

unmute()

Use the unmute method to unmute the video player and revert the previous volume level.

Copy to clipboard
vplayer.unmute()

isMuted

isMuted()

Use the isMuted method to return whether the player is currently muted.

Copy to clipboard
vplayer.isMuted()

currentTime

currentTime(offsetSeconds)

Use the currentTime method to get or set the current time of the video that is playing.

Copy to clipboard
// Seek to the beginning of the video
vplayer.currentTime(0)

duration

duration()

Use the duration method to return the duration of the currently playing video.

Copy to clipboard
vplayer.duration()

maximize

maximize()

Use the maximize method to enter fullscreen mode.

Copy to clipboard
vplayer.maximize()

exitMaximize

exitMaximize()

Use the exitMaximize method to exit fullscreen mode.

Copy to clipboard
vplayer.exitMaximize()

isMaximized

isMaximized()

Use the isMaximized method to return whether video player is in full screen.

Copy to clipboard
vplayer.isMaximized()

Video Player element

fluid

fluid(Boolean)

Use the fluid method to determine whether to responsively resize the video to fit the size of its container or window.

Copy to clipboard
// Create a toggle button that turns the responsive behavior on or off.
<button id="toggle-fluid" class="btn btn-default">Disable Fluid</button>

var player = cld.videoPlayer('example-player');
var source = { publicId: 'oceans'};
player.source(source).play();

// Handle Fluid toggle button
document.querySelector("button#toggle-fluid").addEventListener("click", function() {
isFluid = !player.fluid()
player.fluid(isFluid);

this.innerHTML = isFluid ? 'Disable Fluid' : 'Enable Fluid'
});

height

height(dimension)

Use the height method to get or set the video player’s height.

Copy to clipboard
vplayer.height(490)

width

width(dimension)

Use the width method to get or set the video player’s width.

Copy to clipboard
vplayer.width(430)

dispose

dispose()

Use the dispose method to dispose the video player and remove its element from the DOM.


el

el()

Use the el method to return the video player DOM element.


on

on(event, callback)

Use the on method to register an event handler to the specified event.

Copy to clipboard
var handler = function (event) {
    console.log(event.eventData.percent + " percents played")
}

vplayer.on('percentsplayed', handler)

off

off(event, callback)

Use the off method to unregister an event handler from the specified event.

Copy to clipboard
vplayer.off('percentsplayed', handler)

videoJS

videoJS(Object)

Use the videoJS method to enable you to access all underlying capabilities of the VideoJS API. For details, see the VideoJS Player API.

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.

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

Triggered when player is muted.

unmute

Triggered when player is unmuted.

percentsplayed

Triggered 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.

Copy to clipboard
var vplayer = cld.videoPlayer("my-video", { playedEventPercents: [10, 50, 90] })

vplayer.on('percentsplayed', (event) => {
    console.log(event.eventData.percent + " percents played") 
})

timeplayed

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

Copy to clipboard
var vplayer = cld.videoPlayer("my-video", { playedEventTimes: [60, 120, 180] })

vplayer.on('timeplayed', (event) => {
    console.log(event.eventData.time + " seconds played") 
})

seek

Triggers seekStart and seekEnd data.

Copy to clipboard
vplayer.on('seek', (event) => {
    console.log("Start: " + event.eventData.seekStart + " End: " + event.eventData.seekEnd) 
})

sourcechanged

Triggered when the video player source changes.

qualitychanged

Triggered when the adaptive bitrate quality changes. Returns the video height and width that the player changed from and to.

Copy to clipboard
vplayer.on('qualitychanged', (event) => {
    console.log("Quality changed from: " + event.eventData.from + " to: " + event.eventData.to)  
})

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.

Operation Description
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.
presentUpcoming Gets or sets the presentUpcoming configuration for the playlist.
- A value of false cancels presentation of upcoming videos.
- A value of true activates presentation of upcoming videos 10 seconds before the end of the current video.
- A positive integer value sets the number of seconds before the end of the current video to show the upcoming video.