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.

This reference includes:

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:

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 } })
  • 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"

  • 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.
  • 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 automaticaly 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.

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

  • videoJS (Object) - Enables you to access all underlying capabilities of the VideoJS API. For details, see the VideoJS Player API.

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" 

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(['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 activates the Play command:

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. 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 (String) - The Cloudinary Public ID of the video to play. Can be specified as a standalone parameter or within the options parameter.

      // 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"] })
    • transformation (cloudinary.Transformation, Object, Array or String) - The transformation to apply on the specified video source.

    • 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' } })
    • 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 (Object) - Default transformations to apply to a specific source type. For example:

      vplayer.source('mymovie'), {sourceTransformation({ 'mp4': { width: 410 }}})
    • 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. For example:

      //videoSource definitions
      
      var source1 = {
        publicId: 'movie1', info: {title: 'My wonderful movie', subtitle: 'A movie about movies', description: 'Everything you want to know about this movie.'} }
      
      var source2 = {
        publicId: 'movie2', info: {title: 'Just another movie', subtitle: 'A movie about another movie', description: 'Interesting stuff about movie1.'} }
      
      var source3 = {
        publicId: 'movie3', info: { title: 'Yes another movie', subtitle: 'Part three of the movie series', description: 'Interesting stuff about movie2.'} }
      
      // Recommendations as an array of video source objects
      source1.recommendations = [source2, source3]
      
      // For async fetching of recommendations (e.g. from database), use a Promise
      source2.recommendations = new Promise((resolve, _) => {
        console.log('Going to database...');
        setTimeout(() => {
          console.log('Fetched source from database.', source1)
          resolve([source1]);
        }, 3000);
      })
      • To show the specified recommendations in your player, set the player with autoShowRecommendations: true.
      • For best results, make sure the video sources used as recommendations have titles, subtitles, and descriptions defined, either using the source info parameter or in the context of the resource. For details, see Adding titles, subtitles, and descriptions to your videos.
  • 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'] } })
  • fluid - Boolean. Whether to responsively resize the video to fit the size of its container or window.

    // 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'
    });
  • playlist(sources,{ autoAdvance, repeat, presentUpcoming }) - 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.
    • 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
  • videoJS (Object) - Enables you to access all underlying capabilities of the VideoJS API. For details, see the VideoJS Player API.



    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 '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(tag,{ sorter, sourceParams, autoAdvance, repeat, presentUpcoming }) - 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 - 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 - 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.
    • 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(tag,{ sorter, sourceParams, autoAdvance, repeat, presentUpcoming }) - 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.

  • 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 automaticaly 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.

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

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