How to embed the video player

This section walks you through the steps of embedding self-hosted and cloud-hosted video players, setting them to play a video from your Media Library, and for a self-hosted player, applying commonly used video player methods and properties.

Embed a basic video player

Tip
You can use the Cloudinary CLI to generate the basic code for embedding a video player:

Copy to clipboard
cld make video_player

You can use the self-hosted player by including the Cloudinary Video Player JavaScript library, giving you full control of all your video player instances. Alternatively, you can embed a cloud-hosted player using an iframe. You can easily generate the code for a customized player using the Cloudinary Video Player Studio, or build this out yourself.

Self-hosted player

Embedding a self-hosted player using the Cloudinary Video Player JavaScript-based library requires more setup and configuration than using the cloud-hosted player. It also requires that the library be included in your website or application. Using the video player library gives you more control over the player and playback. We recommend using this method of embedding if you have multiple player instances, need to programmatically control playback and events, or have advanced customization requirements.

1. Include the relevant CSS and JS files for the video player and JavaScript SDK

The video player package is available in standard and light package variations, each available in either minified or non-minified formats. It also requires the JavaScript SDK. You may also need to include additional files depending on the video player features you plan to use.

For example, the following includes the standard, minified package from unpkg.com:

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

For full details on all options, see Installation and setup

2. Embed the video player by adding 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.

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

3. 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. For example, if you're an Advanced plan user with a private CDN and a custom CNAME, you can set private_cdn to true and configure the cname parameter to match your setup. This will ensure the video player delivers your videos using the correct URLs.

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

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

Or for a private CDN and custom distribution:

Copy to clipboard
var cld = cloudinary.Cloudinary.new({ cloud_name: "my-cloud", secure: true, private_cdn: true, secure_distribution: 'example.distribution.com'});

4. Instantiate the Cloudinary video player

Instantiate the video player by using the videoPlayer method and either passing the ID of the video tag ID you defined in step 1, or passing the video element itself. You can optionally add in constructor parameters to set global configurations.

Copy to clipboard
var demoplayer = cld.videoPlayer('demo-player', {<...constructor params here...>} )

Or

Copy to clipboard
var vidElem = document.querySelector("video#demo-player")
var vplayer = cld.videoPlayer(vidElem, {<...constructor params here...>})

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 as you can target the cld-video-player class. As with instantiating a single player, you can optionally add in constructor parameters.

Copy to clipboard
var players = cld.videoPlayers('.cld-video-player', 
 {<...constructor params here...>}
)

5. 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 method. 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 or video URL, 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.

Example 1: Specifying the public ID in the <video> tag:

Copy to clipboard
<video
  id="example-player"
  controls
  muted
  class="cld-video-player cld-video-player-skin-dark"
  data-cld-public-id="myvideo">
</video>


var cld = cloudinary.Cloudinary.new({ cloud_name: 'mycloud' });
var player = cld.videoPlayer('example-player');

Example 2: Specifying the public ID in the videoPlayer method:

Copy to clipboard
<video
  id="example-player"
  controls
  muted
  class="cld-video-player cld-video-player-skin-dark">
</video>

var player = cld.videoPlayer('example-player');
player.source('myvideo');

Example 3: Specifying the video as a URL in the videoPlayer method:

Copy to clipboard
<video
  id="example-player"
  controls
  muted
  class="cld-video-player cld-video-player-skin-dark">
</video>

var player = cld.videoPlayer('example-player');
player.source('http://res.cloudinary.com/demo/video/upload/myvideo.mp4');

For details on other configurations you can set, see Configuration options and the Video Player API Reference.

Cloud-hosted player

The cloud-hosted player uses an iframe to add an instance of the player to your page. The player itself is hosted by Cloudinary and can be easily configured and customized. You can design and configure your player using the Cloudinary Video Player Studio, and then copy and paste the iframe code it generates for you. Alternatively, you can configure the iframe code manually, as outlined below. We recommend using this method if you don't want to host the video player yourself and want to add individual pre-configured video players to your website or application.

This is a simple example of how video player iframe code might look:

Copy to clipboard
<iframe
  src="https://player.cloudinary.com/embed/?cloud_name=demo&public_id=elephants&fluid=true&controls=true&source_types%5B0%5D=mp4"
  width="640"
  allow="autoplay; fullscreen; encrypted-media; picture-in-picture"
  allowfullscreen
  frameborder="0"
></iframe>

Here's how to code your own cloud-hosted player:

1. Add an iframe to your page or application

Add an <iframe> element to your webpage or application in the location you want the video player to appear. For example:

Copy to clipboard
<html>
  <body>
    <!-- Your web page code -->
    <iframe></iframe>
    <!-- Some more of your web page code -->
  </body>
</html>

2. Set the "src" attribute to your Cloudinary Video Player configuration

Set the src attribute of the iframe to add the video player instance to the iframe. The iframe uses the URL of the Cloudinary Video Player embedder service along with your URL encoded parameters.

The URL structure for the service is - https://player.cloudinary.com/embed/?<parameters>

Note
All parameters in the Video Player API reference are listed in camelCase. When used with the embedder, they must be converted to snake_case. For example showLogo becomes show_logo.

Required parameters

Param Type Description
cloud_name String The cloud name for your Cloudinary account.
public_id String The Cloudinary unique identifier for the video.

Optional parameters

Param Type Description
cloudinary Object The account-specific configuration parameters to apply.
player Object The configuration for the player itself, including the player visuals and behavior.
source Object The configuration to apply to the video source.
vpv String The version of the Cloudinary video player to use.

The simplest way to construct your URL is to build your parameters as a single string and append it to the embed URL, for example:

Copy to clipboard
const params = "cloud_name=demo&public_id=elephants&vpv=1.4.0";
const url = "https://player.cloudinary.com/embed/?"+ params;

This will give you the following URL to set as the src of your iframe:

https://player.cloudinary.com/embed/?cloud_name=demo&public_id=elephants&vpv=1.4.0

Tip
If you're using a variety of parameters and configuration, we recommend building your parameter string as an object and then converting to a URI encoded string. You can use a query-string parsing and stringifying library such as qs to help with this.

Here's an example of building the configuration as an object before stringifying it and appending to the embed URL:

Copy to clipboard
const config = { cloud_name: "demo", public_id: "elephants", cloudinary: { cname: "myCname" }, player: { loop: true }, source: { source_types: ['mp4/h265', 'mp4']} };
const params = qs.stringify(config);
const url = "https://player.cloudinary.com/embed/?"+ params;

This will give you the following URL to set as the src of your iframe:

https://player.cloudinary.com/embed/?cloud_name=demo&public_id=elephants&cloudinary%5Bcname%5D=myCname&player%5Bloop%5D=true&source%5Bsource_types%5D%5B0%5D=mp4%2Fh265&source%5Bsource_types%5D%5B1%5D=mp4

The full HTML code for the iframe using the above URL will be:

Copy to clipboard
<iframe 
  src='https://player.cloudinary.com/embed/?cloud_name=demo&public_id=elephants&cloudinary%5Bcname%5D=myCname&player%5Bloop%5D=true&source%5Bsource_types%5D%5B0%5D=mp4%2Fh265&source%5Bsource_types%5D%5B1%5D=mp4'
></iframe>

3. Set additional iframe attributes

In addition to configuring your embed URL, you need to add some attributes to the <iframe> element to allow the video player to behave as expected. You can add any HTML attribute that an iframe element supports. Below are the attributes we recommend setting:

  • Set frameborder="0" to ensure there's no border around your iframe. Alternatively, you could configure this using CSS by setting border: 0; for your iframe.
  • Set the width and height attributes to control the size of the video player.
  • Set the allow attribute to allow the relevant video player functionality, for example if you want to allow the video to be played in fullscreen or play automatically.

For example, to set your iframe to a width of 500 pixels, remove the border and allow autoplay and fullscreen:

Copy to clipboard
<iframe
  src="your-embed-url"
  width="500px"
  allow="autoplay; fullscreen"
  frameborder="0">
</iframe>

Common video player methods and properties

Once you have embedded a video player in your page or app, you can take advantage of the various video player methods and properties to retrieve the current status of elements and perform a wide variety of actions on the player (self-hosted only). 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.

Here are a few simple examples:

  • Set the player volume:

    Copy to clipboard
    vplayer.volume(0.75)
  • Mute the player:

    Copy to clipboard
     vplayer.mute()
  • Jump to the middle of a video:

    Copy to clipboard
    vlength=vplayer.duration()
    middle=vlength/2
    vplayer.currentTime(middle)

All video player methods and properties

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

To view the code for a video player with a set of custom control buttons based on the video player methods, see api.html in the sample CodePen.

✔️ Feedback sent!

Rate this page: