Video player

The Cloudinary Video Player is a JavaScript-based HTML5 video player bundled with many valuable customization and integration capabilities, and is 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.

For example, this video tag and short bit of javascript:

<div style="max-width: 550px">
<video id="doc-player"  controls  muted  class="cld-video-player cld-fluid"></video>
</div>
var cld = cloudinary.Cloudinary.new({ cloud_name: 'demo' });
var demoplayer = cld.videoPlayer('doc-player').width(550);
demoplayer.playlistByTag('video_race', {
  sourceParams: { overlay: "cloudinary_icon", opacity: 80, effect:  "brightness:200", width: 100, gravity: "north_east", x: 20, y: 10 },
  autoAdvance: 0, repeat: true, presentUpcoming: 3
})

Creates a responsively resizing video player with an automatically generated playlist (based on a specified tag) that displays titles, subtitles, a logo overlay, and next-up preview:

This guide covers:

See also: Video Player API Reference

Video Player features

  • Broad device support: The webview player is 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.

  • Video manipulations: Apply Cloudinary video transformations at the player level that will apply to all videos delivered in that player. Apply additional or override video transformations at the per-video level.

  • Multiple players: Include multiple players on the same page, each with different configuration settings, or with different sources and the same configuration.

  • 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, display of titles and subtitles and other 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: Pass a list of videos or automatically include all videos that have a specified tag. Display a Next up thumbnail towards the end of each video in the list.

  • Recommendations: Display recommended videos when a video ends.

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

Video Player installation and setup

The Cloudinary video player offers full and light package variations, available in either minified or non-minified formats.

  • Full package: Includes all functionality described in this document, except MPEG-DASH support.
  • Light package: Excludes the following optional functionality: HLS support.

Note: You can add MPEG-DASH support separately to either package.

Full Light
Non-minified cld-video-player.js
cld-video-player.css
cld-video-player.light.js
cld-video-player.light.ss
Minified cld-video-player.min.js
cld-video-player.min.css
cld-video-player.light.min.js
cld-video-player.light.min.css

To include a video player on an HTML page, you can either reference the relevant video player package files directly from Unpkg CDN or you can install the complete video player package locally and then reference the relevant local files.

Option 1: Reference the relevant video player and JavaScript SDK files directly from 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>

Option 2: Install the video player and javascript packages and then include the required CSS and Javascript

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

    npm install lodash cloudinary-core cloudinary-video-player
  2. Reference the relevant local CSS and JavaScript files:

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

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

Enabling MPEG-DASH support for your video player

If you plan to deliver videos in your video player using MPEG-DASH files, include the following files in addition to the files described above:

<script src="https://cdnjs.cloudflare.com/ajax/libs/dashjs/2.6.3/dash.all.min.js" type="text/javascript"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/videojs-contrib-dash/2.9.2/videojs-dash.min.js" 
    type="text/javascript"></script>

Afterwards, you can specify dash as the the sourceType for your video source, as described in Delivering videos with HLS or MPEG-DASH.

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 and Cloudinary Video Player CodePen.

Adding a Video Player and video to your page

1. Add a video tag 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>

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.

Video player skin themes

By default, the video player has a semi-transparent dark theme. The theme you select controls the color of the video player controls, controls background color, title style, and the color of the right-click context menu commands and central play button. You can change the theme skin by adding the class: cld-video-player-skin-<value> to the video tag. For example, to specify the light theme, include this in your <video> tag:

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

The images below demonstrate the built-in dark and light themes:

video player with light skin Light skin theme video player with dark skin Dark skin theme

Common configurations

Set the video to play

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

Define 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}})

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

Default Configuration Behaviors

Most standard HTML5 video attributes (autoplay, loop, preload, muted, etc) retain their standard default behavior (auto mode for preload and false for all others).

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.

Adding titles, subtitles, and descriptions to your videos

Video titles, subtitles, and descriptions can help give your audience quick information about your video. This information is displayed as follows:

  • The title and subtitle at the top of the video player whenever the controls are displayed
  • The title is displayed when 'Next up' thumbnails are presented in your playlists. If a title is not defined, the public ID of the video is used instead.
  • The title, subtitle, and description are displayed for the primary video recommendation when recommendations are enabled. The title is displayed for the remaining recommendations.

For Upcoming video thumbnails in playlists and for recommendations, if titles are not defined, public ID's are displayed instead. In all other cases, if any of these parameters are not defined, they are simply omitted in the display.

For example, the recommendation pane below shows the title, subtitle, and description of the main recommendation video, and titles where defined for the remaining recommendations. Note that the last recommendation shows the public ID because no title was defined.

Video recommendations pane with titles and descriptions

You can add titles, subtitles, and descriptions directly to the video resources in your account by adding them to the resource context using the Upload or Context methods of the Upload API or via the Media Library.

You can also define the title, subtitle, and/or description at the source-level in the <video> tag or or videoPlayer javascript using the info parameter:

  • In the <video> tag:
data-cld-source='{ "publicId": "myvideo", "transformation": { "width": 200 }, "info": { "title": "My Title", "subtitle": "Something about the video" "description": "More detail about the video" } }'>
  • For a videoPlayer source:
player.source({'oceans', info: { title: 'My Title', subtitle: 'Something about the video', description: 'More detail about the video' } })

If the info parameter is set for a source, its values override the parallel entries in the resource context.

Delivering videos with HLS or MPEG-DASH

The built-in video players available with many desktop and mobile browsers do not support HLS and/or MPEG-DASH adaptive bitrate streaming 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.

Note: If you plan to deliver in MPEG-DASH format, make sure you reference the required MPEG-DASH files in addition to the video player files. For details, see Enabling MPEG-DASH support for your video player.

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": {"streaming_profile": "hd"}}'
data-cld-source-types='["hls"]'

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, repeat, and presentUpcoming 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).

When creating a playlistByTag with the presentUpcoming parameter or when autoShowRecommendations is true, the titles, subtitles, and descriptions are automatically taken from the title entry of the resource's context data if it exists. Otherwise the public ID is used instead. You can add a video title (as well as a subtitle and description) to the resource context using the Upload or Context methods of the Upload API or via the Media Library.

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, and the upcoming video thumbnail will display 5 seconds before the end of each video. When the promise is fulfilled, the console log displays a message:

player.playlistByTag("demo"
{ sourceParams: { angle: 10 }, autoAdvance: 0, repeat: true, presentUpcoming: 5 })
.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.

Present the upcoming video

When using playlists, you can optionally display a thumbnail and the title of the upcoming video a few seconds before the current one ends, using the presentUpcoming parameter.

Set presentUpcoming to true, to display the upcoming video at the default time of 10 seconds before the end of the video. Alternatively, specify how many seconds before the end of the video the thumbnail should display.

For example:

player.playlist([source1, source2], { autoAdvance: true, repeat: true, presentUpcoming: 8 });

present upcoming thumbnail in playlist

Notes:

  • If your playlist is set to repeat, then the upcoming video thumbnail shows the first video when the last video nears the end. Otherwise, no upcoming video is displayed at the end of the list.

  • If you have not set a title for a particular source in your playlist, either in the context of the resource itself or in the <video> tag or videoPlayer source definitions, then the source's public ID is displayed instead of the title. For details, see title values.

Showing video recommendations

You can set your video player to show up to four video recommendations in a recommendations overlay pane when a video finishes playing. This can be for an individual video, or at the end of each video in a playlist as long auto-advance is disabled (autoAdvance: false). The recommendations pane displays one primary recommendation including large thumbnail, title, subtitle, and description (if they are defined for the relevant source), followed by up to three secondary recommendations, with a smaller thumbnail and the video title or public ID.

Video recommendations pane with titles and descriptions

To include recommendations at the end of a video, you need to:

  1. Pass autoShowRecommendations: true when creating the player, or trigger player.autoShowRecommendations(true) at a later time.
  2. Add a recommendations parameter to each video source for which you want to show recommendations after it. The parameter value is an array of video source objects (or a function or Promise that resolves into an array of video source objects).

For best results, make sure that each source you define as a recommendation has a title, sub-title, and description defined, either in the source definition or in the context of the resource itself.

For example:

// Setting video sources:
var source1 = { publicId: 'movie1', info: { title: 'My main movie', 
   subtitle: 'Something to know about the main movie' } }
var source2 = { publicId: 'movie2', info: { title: 'The next best video', 
   subtitle: 'A great subtitle', 
   description: 'An interesting description of this video....' } }
var source3 = { publicId: 'movie3', info: { title: 'Another interesting video1', 
   subtitle: 'Subtitle for video1' } }
var source4 = { publicId: 'movie4', info: { title: 'Another interesting video2', 
   subtitle: 'Subtitle for video2' } }
var source5 = { publicId: 'movie5', info: { title: 'Another interesting video3', 
   subtitle: 'Subtitle for video3' } }

// Specifying the recommendations for source1 as a fixed array of sources:
source1.recommendations = [source2, source3, source4, source5]

// Initializing the player with recommendations turned on
var player = cld.videoPlayer('example-player', { autoShowRecommendations: true });
player.source(source1);


Notes for using recommendations with playlists:

  • If you create a playlist with auto-advance disabled (autoAdvance: false) and autoShowRecommendations: true, then by default, the next videos in the playlist are automatically displayed as the recommendations. In this case, if a viewer selects one of the recommendations, they remain within the context of the playlist.

  • If you explicitly specify recommendations for the sources in your playlist, those are displayed in the recommendations pane. In this case, if a viewer selects one of the recommendations, they exit the playlist.

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.

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 property. For details, see the VideoJS Player API.