Video player customization

You can customize your video player in a number of ways.

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

Configuration options

You can set most configuration options either in your video tag or using JavaScript.

This section covers:

Common configuration examples

Set the video to play

  • In the <video> tag:
  • In the videoPlayer:

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

For information on available video transformations, see:

Additional common configurations

Some additional common configurations include:

  • Setting the autoplay mode. For example, use on-scroll to cause the video to start playing when more than half the player is visible on screen.
  • Setting a specific image as the video poster, including applying image transformations on the specified image.
  • Defining the preferred set of video formats. By default the video format set is mp4, ogg, and webm, where the player selects the best format to play based on the browser in which the player is running.

  • In the <video> tag:

   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"],

The above are just a few common options. For details on all available options, see the Video Player configuration options section in the Video Player API Reference.

Additionally, see index.html in the sample CodePen for an implementation example with many of these configuration settings.

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.

Video titles, subtitles and descriptions

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.

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.