Last updated: Apr-08-2023
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
For example, the following includes the standard, minified package from unpkg.com:
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.
3. 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.
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 player, for example:
Or for a private CDN and custom distribution:
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.
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 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, and the poster source per video source, using
data-cld-source attribute in the
<video> tag), and then set different values for these options for each video source you play.
For optimal delivery, you can also define the source types you want the player to use. This can include a combination of advanced formats and codecs as well as adaptive bitrate streaming formats. The player will attempt to play the source type listed first and fallback to the subsequent formats. This helps provide the most optimal video delivery depending on the browser and device.
<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:
Example 2: Specifying the public ID in the videoPlayer method:
Example 3: Specifying the video as a URL in the videoPlayer method:
Example 4: Specifying multiple source types:
For details on other configurations you can set, see Configuration options and the Video Player API Reference.
Recommendations for optimal performance
When embedding the self-hosted player, you can embed and configure it in a number of different ways. Some of these provide better performance than others. Here are some recommendations on how to embed the player for the most optimal performance.
- Use the light package if you aren't using adaptive bitrate streaming, video ads or shoppable video functionality.
- Ensure your page loads the video player libraries and HTML in the following, most optimal, order:
- Video player stylesheet
- HTML for the video element
- Use the
cld-fluidclass for responsive player sizing. This should be used over any JS configuration method to prevent unwanted player resizing.
Below is a very simple example demonstrating how you should organize your code for the video player using the recommendations above:
Video tutorial: Embed the Video Player in a React app
Watch this video tutorial to learn how to embed the Video Player in a React app:
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:
Here's how to code your own cloud-hosted player:
1. Add an iframe to your page or application
<iframe> element to your webpage or application in the location you want the video player to appear. For example:
2. Set the "src" attribute to your Cloudinary Video Player configuration
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 -
|cloud_name||String||The cloud name for your Cloudinary product environment.|
|public_id||String||The Cloudinary unique identifier for the video.|
|cloudinary||Object||The Cloudinary product environment-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:
This will give you the following URL to set as the
src of your iframe:
Here's an example of building the configuration as an object before stringifying it and appending to the embed URL:
This will give you the following URL to set as the
src of your iframe:
The full HTML code for the iframe using the above URL will be:
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:
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
heightattributes to control the size of the video player.
- Set the
allowattribute 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:
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:
Mute the player:
Jump to the middle of a video:
All video player methods and properties
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.
For details and code examples for all available video player operations, see the video player methods and playlist operations in the Video Player API Reference.
Eagerly generating video player URLs
When embedding the video player in your web or mobile application, you can use of a number of configuration parameters to control how your videos look and how they are delivered to your end users. The Cloudinary Video Player itself will also apply some defaults for the delivery formats to ensure optimized performance and wide browser support. As a result, the URLs that are used for delivery will often include some transformations. If you're working with larger videos that exceed the file-size limitations for transforming videos on the fly (40 MB for free plans, 100 MB for paid plans), you will need to ensure that you eagerly generate the right URLs to match your configuration.
For example, the default sourceTypes for the video player are
['webm/vp9','mp4/h265','mp4']. This means that the video player will try and deliver a
webm version using the
vp9 codec before falling back to the others if it is unable to deliver that version. In this scenario, if your original file is an
mp4 and the file size exceeds the on-the-fly limit, the
webm version will not be generated and the player will need to fallback to a less optimal version. To resolve this, you can ensure that when you upload your videos, you eagerly generate the URLs you require. The same principle applies if you use any transformations on your videos.
Here's an example of a video player configuration that includes three source types and two transformations to apply to all videos. This is followed by the code required to eagerly generate the matching derived versions of each video.
Simple video player html:
The configuration above will generate three delivery URLs, one for each of the defined source types and all three including the transformations we have defined:
To ensure that the above URLs are generated and ready for delivery, you can create these eagerly on upload. Here's how to upload your videos with the relevant transformations:
The example code above processes the eager transformations asynchronously and sends a notification to the defined URL once complete and ready for delivery.
Rather than defining the required eager transformations in your code, you could make use of upload presets instead, allowing you to define the matching eager transformations once and use this for all uploads. This means that if you need to change your video player configuration, you would only need to update your upload preset configuration and your code would still generate the correct URLs.
You can create your upload preset using the Cloudinary console or alternatively you can do this programmatically.
Once you have your upload preset, you can use it with your upload code as shown below.
- Customize your video player
- Learn more about the video effects and transformations you can apply to your videos
- Deliver your videos using HLS or DASH adaptive bitrate streaming formats
- Define playlists and set up video recommendations
- Check out all the video player options in the Video Player API Reference