Video player

The Cloudinary Video Player is a JavaScript-based HTML5 video player bundled with many valuable customization and integration capabilities, and is monetization and analytics-ready. The player is fully integrated with Cloudinary's video delivery and manipulation solution and it takes just a few lines of code to embed a player into your web page.

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

This guide covers:

See also: Video Player API Reference

Video Player features

  • Devices: Webview player designed for both desktop and mobile web browsers on a wide range of devices
  • Player controls: Built-in support of all standard player controls: play, pause, mute/unmute, volume control, loop, maximize/exit maximize, with the option for full customization.
  • Multiple players: Include multiple players on the same page, each with different configuration settings, or with different sources and the same configuration.
  • Video manipulations: Apply Cloudinary video transformations at the player level that will apply to all videos delivered in that player. Then apply additional or override video transformations at the per-video level.
  • Formats: Supports popular video formats, such as .mp4, .ogv, .webm, .mov. You can specify multiple formats and the player automatically selects the best format for the browser where it's playing.
  • Adaptive bitrate streaming: Full support for HLS and MPEG-DASH including automatic generation of all required streaming representations and supporting files.
  • Customization:
    • Simple parameters to adjust skin themes and customize basic player preferences
    • Events that enable you to trigger operations based on both passive and interactive actions that occur in your player.
    • Access to the underlying videojs API for low-level control or customization of any element of the player.
  • Playlists: Manually specify a list of videos or include all videos from your Cloudinary account with a specified tag.
  • Analytics: Monitor how many users are viewing your video and when, down to the level of any events you choose (start, pause, watched duration percentages, and more) and then pass the captured data to your Google Analytics account or other analytics trackers.
  • Monetization: The player is monetization-ready, with support for both VAST and VPAID formats.

Video Player installation and setup

Install the files using the NPM package manager:

  1. Install the cloudinary-video-player together with the Cloudinary JavaScript package and lodash if these are not already installed:

    npm install lodash cloudinary-core cloudinary-video-player
  2. Include the following CSS and JavaScript files in HTML page(s) where you want to include the video player:

    <link href="node_modules/cloudinary-video-player/dist/cld-video-player.min.css" rel="stylesheet">
    <script src="node_modules/lodash/lodash.js" type="text/javascript"></script>
    <script src="node_modules/cloudinary-core/cloudinary-core.js" type="text/javascript"></script>
    <script src="node_modules/cloudinary-video-player/dist/cld-video-player.min.js" type="text/javascript"></script>

Alternatively, instead of using NPM, the Cloudinary Video Player and JavaScript package can also be included directly from the Unpkg CDN:

<link href="https://unpkg.com/cloudinary-video-player/dist/cld-video-player.min.css" rel="stylesheet">
<script src="https://unpkg.com/cloudinary-core/cloudinary-core-shrinkwrap.min.js" type="text/javascript"></script>
<script src="https://unpkg.com/cloudinary-video-player/dist/cld-video-player.min.js" type="text/javascript"></script>

For more information on the Cloudinary JavaScript package, see JavaScript integration.

Video Player samples

You can view sample HTML and JavaScript code for the features described in this document in the the Cloudinary Video Player Demo codepen.

Adding a Video Player and video to your page

1. Add a <video> element with the video player class

Create a video tag with at least the cld-video-player class and an id value. You can also include standard HTML5 video player attributes.

<video
  id="demo-player"
  controls
  autoplay
  class="cld-video-player">
</video>

By default, the video player has a blue theme. The theme you select controls the color of the video player controls and the right-click context menu commands. You can change the theme skin color by adding the class: cld-video-player-skin-<color> to the video tag. For example:

  class="cld-video-player cld-video-player-skin-yellow"

video player with yellow skin

2. Instantiate a Cloudinary instance with your cloudinary configuration:

To use the Cloudinary Video Player library you have to configure at least your cloud_name. You can additionally define a number of optional configuration parameters if relevant.

You set configuration parameters while instantiating a new Cloudinary class, for example:

var cld = cloudinary.Cloudinary.new({ cloud_name: "my-cloud", secure: true});

3. Instantiate the Cloudinary video player

Instantiate the videoPlayer using the video tag ID you defined in step 1, or using a video element and query selector.

var demoplayer = cld.videoPlayer('demo-player')

Or

var vidElem = document.querySelector(video#demo-player)
var vplayer = cld.videoPlayer(vidElem)

If you plan to include multiple players on your page with the same configuration, you can use the videoPlayers method. For example, you can specify different video public IDs for each <video> tag. In this case, there is no need to define id attributes for the <video> tags.

var players = cld.videoPlayers('.cld-video-player', 
 {<...configurations here...>}
)

4. Specify the video to play and optional player configurations

You can specify the video to play, the transformations to apply, as well as a number of additional configurations either as attributes of the <video> tag or as constructor parameters of the videoPlayer. These configurations and transformations apply to the video player itself, and thus will apply to all video sources played inside it.

You can additionally specify some options like the video public ID, video transformations, source type, and the poster source per video source, using videoPlayer.source (or data-cld-source attribute in the <video> tag), and then set different values for these options for each video source you play.

For the <video> tag, all special Cloudinary video player configurations have a data-cld- prefix. Standard HTML5 video attributes are specified as usual.

Basic configurations

To specify the video to play:

  • In the <video> tag:
data-cld-public-id="oceans"
  • In the videoPlayer:
player.source({'oceans'})

To specify video transformations:

  • In the <video> tag:
  data-cld-transformation='{ "crop": "limit", "width": 500}'>
  • In the videoPlayer:
     var player = cld.videoPlayer('demo-player', {
     transformation: {crop: 'limit' width: 200}
   })
  • For a specific videoPlayer.source:
player.source({'oceans', transformation: {angle: 10}})

To specify other configurations:

  • In the <video> tag:
   ...  
   loop
   controls
   data-cld-public-id="book"
   data-cld-autoplay-mode="on-scroll"
   data-cld-transformation='{ "width": 400, "crop": "limit",  
     streaming_profile": "hd" }'
   data-cld-poster-options='{ "public_id": "mypic" "transformation": 
    {"effect": ["sepia"] } }'
   data-cld-source-types='["hls", "mp4"]'
   ...
  • In the videoPlayer:
 var vplayer = cld.videoPlayer("demo-player", {
   publicId: book,
   loop: true,
   controls: true,
   autoplayMode: 'on-scroll',
   transformation: { width: 400, crop: 'limit ' },
   posterOptions: {publicId: mypic, transformation { effect: [sepia]}},
   sourceTypes: ["hls", "mp4"],
 })

See index.html in the sample CodePen for a basic implementation example.

For details on all available options, see the Video Player configuration options section in the Video Player API Reference.

Defaults

All standard HTML5 parameters (autoplay, loop, preload, muted, and controls) retain their standard default behavior (false for all, and auto mode for preload).

By default, the video player automatically uses the middle image of your video as a poster image (the equivalent of <cloud_name>/video/<type>/<videoID>.jpg). You can specify a different public ID and/or image transformations using the posterOptions (data-cld-poster-options) setting.

Additionally, by default, when the player requests your video, it will automatically request the best format from the default source types (.webm, .ogg, and .mp4). If the transformation defined already exists for the requested source type, it's delivered. Otherwise, the relevant transformation is transcoded and streamed in real time. You can override the default format options using the sourceTypes (data-cld-source-types) setting.

Configuration Precedence

You can set transformations and a number of other configurations either in the <video> tag or in the videoPlayer instance. In both cases, they define the defaults that will apply to all video sources. You should not include the same configuration parameter in both the tag and the JavaScript element, but if you do, the JavaScript setting will take precedence.

In general, if you set the same configuration parameter for a specific video source, those values override the values of the parallel setting for the player.

However, if transformations are defined for both the source and the player, the transformation definitions are merged. For example, you could define width, height, and text overlay transformations at the player level, and then apply some special effect transformations for a particular video source. The resulting video will include all of the above transformations.

The cloudinary autoPlayMode (data-cld-autoplay-mode) is similar to the standard HTML5 autoplay parameter, but includes additional possible values. You should not include both settings in your player, but if you do, the Cloudinary autoplay mode setting takes precedence.

Delivering videos with Adaptive Bitrate Streaming (HLS or MPEG-DASH)

The built-in video players available with many desktop and mobile browsers do not support HLS and/or MPEG-DASH formats. By embedding the Cloudinary video player in your application, you can deliver any HLS or MPEG-DASH video. By using this capability in conjunction with Cloudinary's automatic transcoding from standard video formats to HLS or MPEG-DASH, including generation of all related files and video representations, you can stream any video in your Cloudinary account to your users according to the bandwidth and CPU capacity that the video player detects in real-time.

1. Transcode your video to HLS or MPEG-DASH ahead of time.

When you upload your video to your Cloudinary account, or using the explicit method, include an eager transformation with your desired streaming profile and adaptive streaming format. This ensures that all required files and video representations are generated and ready to be delivered upon request.

For detailed information and instructions on transcoding to HLS or MPEG-DASH and the options for streaming profiles, see Adaptive bitrate streaming - HLS and MPEG-DASH.

2. Specify the streaming format and streaming profile for the videoPlayer source file.

When you specify the video source file to play, use the sourceTypes method (or data-cld-source-types) to specify hls or dash, and in the transformation, include the streaming profile you want to use. Make sure the complete transformation is identical to the one you provided in your eager transformation (as per the URL that was returned in the upload response).

For example:

player.source('oceans', { sourceTypes: ['hls'], transformation: {
 streaming_profile: 'hd' } })

Or

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

Creating a playlist

Use the videoPlayer.playlist method to create a set of videos to play in your video player. You can define a list of public IDs to include, and optionally set transformations for each source. Alternatively, you can generate a playlist based on all videos in your Cloudinary account with a specified tag.

After you have defined a playlist, you can use playlist methods to control the list. For example, you can jump to the next or previous video, jump to a specific video in the playlist by index, determine whether to auto-advance to the next video when the previous one ends, retrieve the total number of videos in the list, and more.

Create a fixed source playlist

The following example creates a playlist with the videos IDs: book, ocean, and dog. The book video plays with a transformation that overrides the default player settings. The next video in the list automatically begins 10 seconds after the previous, and then repeats the playlist from the beginning after the last video ends.

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

See playlist.html in the sample CodePen to see a sample video player with a play list, including Next and Previous buttons.

For details on all available playlist methods, see Playlist operations in the Video Player API Reference.

Create a playlist for a specified tag

The playlistByTag method performs a call to the client-side resource list operation and returns a promise object that when fulfilled, returns the player with the playlist.

Note: To enable this functionality, make sure that the Resource list option is not restricted in your account settings: In the Cloudinary console, go to Settings > Security > Restricted image types, and make sure the Resource list option is not selected.

The playlistByTag method receives the tag to use and a set of options. In addition to setting the autoAdvance and repeat parameters, you can also optionally provide a sorter (receives the name of a function that determines the sort order of the retrieved set of videos) and a sourceParams object (enables you to set transformations that will be applied to all the retrieved videos in the playlist).

The following example generates (the promise of) a playlist from all videos with the tag, "demo". It will deliver all retrieved sources with a 10 degree angle rotation transformation. The playlist is set to play each video in succession with no delay and then reloop to the beginning of the playlist. When the promise is fulfilled, the console log displays a message:

player.playlistByTag("demo"
{ sourceParams: { angle: 10 }, autoAdvance: 0, repeat: true })
.then(function(player) 
{
            console.log("Playlist loaded")
 })

See playlistByTag.html in the sample CodePen to see a playlist generated by tags, including a sorter function.

You can also use the sourcesByTag method to retrieve the sources for a specified tag without actually creating the playlist. This method has the same syntax and supports the same options as the playlistByTag.

The example below retrieves (the promise of) the sources data from all videos with the tag, "demo". When the promise is fulfilled, it passes the sources to the playlist method.

player.sourcesByTag("demo")
  .then(function(sources) { 
    player.playlist(sources)
  })

For details on all available playlist methods, see Playlist operations in the Video Player API Reference.

Performing operations on your player

Once you have created a video player, you can take advantage of the videoPlayer methods to retrieve the current status of various elements and perform a wide variety of operations. For example, you can retrieve or change the video source that is playing, jump to a specific place in the video, activate video control operations like play, pause, stop, play next or previous, mute/unmute, adjust volume, maximize, and more.

For example:

  • Set the player volume:

    vplayer.volume(0.75)
  • Retrieve the total duration of the video that is currently playing:

    vlength=vplayer.duration()
  • Mute the player:

     vplayer.mute()

See api.html in the sample CodePen to view the code for a video player with a set of custom control buttons based on the videoPlayer methods.

For details on all available videoPlayer operations, see VideoPlayer methods in the Video Player API Reference.

Using video events

You can register to a long list of standard HTML5 video events as well as several specific 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 example, you can define a set of percentages that will trigger the percentsplayed event and then perform some operation when the player reaches any of those points. Below, the captured percentages are written to the console log:

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

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

See api.html in the sample CodePen to view the code for a video player with a set of custom control buttons. The events triggered by these buttons written to a dynamic log displayed on the HTML page.

For details on all available events, see Events in the Video Player API Reference.

Capturing analytics data

You can track important data about how and when your customers are watching your videos by capturing relevant events. You can then pass this data to your Google Analytics account or other analytics trackers. The instructions below are specific to Google Analytics.

1. Activate analytics in your videoPlayer

You can either set the analytics parameter to true, which monitors all available events except timeplayed (percentplayed is monitored), or you can specify the specific events you want to monitor, including additional event sub-settings where relevant ('percentsplayed', percents and 'timesplayed', times. See example below).

var vplayer = cld.videoPlayer({ ... , analytics: true })

Or

var vplayer = cld.videoPlayer({ ... , analytics: { 
  events: [play, pause, ended, { type: percentsplayed, percents: [10, 40, 70, 90] }, error]
} })

2. Include the Google Analytics code snippet in your page.

Include the Google Analytics tracking snippet with your Google tracking ID near the top of the tag in your HTML page.

For details, see Google Analytics tracking snippet.

Monetizing your videos

The Cloudinary video player is monetization-ready, with support for both VAST and VPAID formats. Contact us to enable this option.

Low-level customization with video.js

The Cloudinary video player is built over the VideoJS player. You can access all underlying capabilities of the VideoJS API, using the vplayer.videojs method. For details, see the VideoJS Player API.