> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# How to embed the Video Player


[//]: # (PageTitle: How to embed the video player)

## Overview

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

> **TIP**: You can use the [Cloudinary CLI](cloudinary_cli#make) to generate the basic code for embedding a video player: 

```
cld make video_player
```

You can use the [self-hosted player](#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](#cloud_hosted_player) using an iframe. You can easily generate the code for a customized player using the [Video Player Studio](video_player_studio), or build this out yourself.

> **INFO**: The [Video Player Studio](video_player_studio) allows you to configure player settings visually and save them directly to video assets. You can then generate embed code that automatically applies those saved settings.

## Self-hosted player

Embedding a self-hosted player using the Cloudinary Video Player JavaScript-based library offers greater control over the player and playback settings. However, it requires a little more setup and configuration than the [cloud-hosted player](#cloud_hosted_player), and you must include the library in your website or application. We recommend using this method of embedding if you have multiple player instances, need to programmatically control playback and events, or have advanced customization and performance requirements.

You can also take advantage of [player profiles](#player_profiles) to define your configuration, allowing you to easily make changes without having to deploy your code.

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

Import the video player and any additional modules, or include the video player scripts from a CDN in your pages.

To import as a module:

```js
import cloudinary from 'cloudinary-video-player';
import 'cloudinary-video-player/cld-video-player.min.css';

//Additional modules added if required, for example:
import 'cloudinary-video-player/chapters';

```

If you're including from a CDN, the video player package is available in either minified or non-minified formats. Core functionality is loaded initially, with additional modules loaded lazily as required.

For example, the following includes the standard, minified package and css from cdnjs:

```html<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/cloudinary-video-player@3.10.0/dist/cld-video-player.min.css" crossorigin="anonymous" referrerpolicy="no-referrer" />
<script src="https://cdn.jsdelivr.net/npm/cloudinary-video-player@3.10.0/dist/cld-video-player.min.js" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
```

For full details on all options, see [Installation and setup](cloudinary_video_player#installation)

> **NOTE**: When using both the [Upload Widget](upload_widget) and [Video Player](cloudinary_video_player) on the same page, the video player scripts must be loaded first to prevent any conflicts.

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

```html

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

### 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](video_player_api_reference#constructor_parameters) to set global configurations.

```js
const demoplayer = cloudinary.videoPlayer('demo-player', {<...constructor params here...>} )
```
Or 

```js
const vidElem = document.querySelector("video#demo-player")
const vplayer = cloudinary.videoPlayer(vidElem, {<...constructor params here...>})
```

To use the Cloudinary Video Player library you have to configure at least your `cloudName`. You can additionally define a number of optional [configuration parameters](cloudinary_sdks#configuration_parameters). For example, if you're an [Advanced plan](https://cloudinary.com/pricing) user with a private CDN and custom delivery hostname (CNAME), you can set `privateCdn` 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:

```js
const cld = cloudinary.videoPlayer('player',{ cloudName: "my-cloud", secure: true, {<...constructor params here...>} });
```
Or for a private CDN and custom distribution:

```js
const cld = cloudinary.videoPlayer('player',{ cloudName: "my-cloud", secure: true, privateCdn: true, secureDistribution: 'example.distribution.com'});
```

> **INFO**: For Video Player versions earlier than `1.9.15`, [configuration parameters](cloudinary_sdks#configuration_parameters) including your cloud name must be specified in snake_case. All examples in the documentation now use camelCase for consistency with the rest of the video player options. Using snake_case will continue to be supported, however you must upgrade your video player version to at least `1.9.15` if you wish to use any camelCase examples.

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](video_player_api_reference#constructor_parameters).

```js
const players = cloudinary.videoPlayers('.cld-video-player', 
 {<...constructor params 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` 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 `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 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](video_player_hls_dash) formats. The player will attempt to play the source type listed first and fallback to the subsequent formats. This helps provide the optimal video delivery depending on the browser and device.

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

When setting the video player source and any transformations or source types, you will be adjusting the final delivery URLs that the video player will use. As a result, new derived versions of the videos will need to be generated. For longer form videos, we recommend that you [eagerly generate](#eagerly_generating_video_player_urls) these derived versions on upload or use the [explicit method](image_upload_api_reference#explicit_method) of the Upload API.

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

```html
<video
  id="example-player"
  controls
  muted
  class="cld-video-player cld-video-player-skin-dark"
  data-cld-public-id="myvideo">
</video>

const cld = cloudinary.videoPlayer('example-player',{ cloudName: 'mycloud' });
```

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

```js
<video
  id="example-player"
  controls
  muted
  class="cld-video-player cld-video-player-skin-dark">
</video>

const cld = cloudinary.videoPlayer('example-player',{ cloudName: 'mycloud' });
cld.source('myvideo');
```

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

```html
<video
  id="example-player"
  controls
  muted
  class="cld-video-player cld-video-player-skin-dark">
</video>

const cld = cloudinary.videoPlayer('example-player',{ cloudName: 'mycloud' });
cld.source('http://res.cloudinary.com/demo/video/upload/myvideo.mp4');
```

#### Example 4: Specifying multiple source types

```js
<video
  id="example-player"
  controls
  muted
  class="cld-video-player cld-video-player-skin-dark">
</video>

const cld = cloudinary.videoPlayer('example-player', { 
    cloudName: 'mycloud',  
    sourceTypes: ['hls','dash','webm/vp9','mp4/h265','mp4']});
cld.source('myvideo');
```

> **NOTE**: If you are importing the video player as a module, you will also need to import any [relevant modules](cloudinary_video_player#available_modules) for advanced functionality.

For details on other configurations you can set, see [Configuration options](video_player_customization#configuration_options) and the [Video Player API Reference](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 optimal performance.

* Use the [light](cloudinary_video_player#installation) package/module if you aren't using additional functionality such as adaptive bitrate streaming, video ads or shoppable video. 
* Ensure your page loads the video player libraries and HTML in the following, optimal, order:
  1. Video player stylesheet
  2. HTML for the video element
  3. Video Player JavaScript libraries.
  4. JavaScript to configure your video player.
* Use the `cld-fluid` class for responsive player sizing. This should be used over any JS configuration method to prevent unwanted player resizing.

> **TIP**:
>
> `cld-fluid` controls responsive **layout** sizing (the player element resizes with its container). To also optimize the video **resolution** for the display, enable [responsive breakpoints](video_player_customization#responsive_breakpoints).

Below is a very simple example demonstrating how you should organize your code for the video player using the recommendations above:

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/cloudinary-video-player@3.10.0/dist/cld-video-player.min.css" crossorigin="anonymous" referrerpolicy="no-referrer" />
    <title>Video Player Demo</title>
  </head>

  <body>
    <video
      id="player"
      class="cld-video-player cld-fluid"
      controls
      playsinline
    ></video>

    <script src="https://cdn.jsdelivr.net/npm/cloudinary-video-player@3.10.0/dist/cld-video-player.min.js" crossorigin="anonymous" referrerpolicy="no-referrer"></script>

    <script>
      const cld = cloudinary.videoPlayer('player',{ cloudName: 'mycloud' });
      cld.source("dog");
    </script>
  </body>
</html>
```

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

  This video is brought to you by Cloudinary's video player - embed your own!Use the controls to set the playback speed, navigate to chapters of interest and select subtitles in your preferred language.

#### Tutorial contents This tutorial presents the following topics. Click a timestamp to jump to that part of the video.
#### Introduction to the Cloudinary Video Player
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media1 :min=0 :sec=00 :player=cld} | The [Cloudinary Video Player](cloudinary_video_player) allows you to embed videos in your React app with just a few lines of code.
|

#### Create a VideoPlayer component
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media1 :min=0 :sec=15 :player=cld} | Start with a basic React application and add a new file called **VideoPlayer.js** in which you can create a component for the Video Player.
|

#### Embed the Video Player script
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media1 :min=0 :sec=29 :player=cld} | Copy the `link` tag from the [Installation and setup](cloudinary_video_player#installation) section of the docs and paste it into the `<head>` of the **public/index.html** file. Then, copy the `script` tag and paste it into the `<body>` of the same file.
|

#### Initialize the Video Player
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media1 :min=1 :sec=08 :player=cld} | Use the following code in **VideoPlayer.js** to initialize the VideoPlayer.  Make sure to use your own cloud name instead of `colbycloud-examples`.
|

```react
import { useEffect, useRef } from 'react';

function VideoPlayer = () {
  const cloudinaryRef = useRef();
  const videoRef = useRef();

  useEffect(() => {
    if ( cloudinaryRef.current ) return;

    cloudinaryRef.current = window.cloudinary;
    cloudinaryRef.current.videoPlayer(videoRef.current, {
      cloud_name: 'colbycloud-examples'
    })
  }, []);

  return (
      <video
        ref={videoRef}
      />
  );
}

```

#### Specify the video to play
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media1 :min=2 :sec=56 :player=cld} | In the `<video>` element set the `data-cld-public-id` property to the [public ID](cloudinary_glossary#public_id) of the video you want to play. 
|

#### Use the VideoPlayer component
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media1 :min=3 :sec=14 :player=cld} | In your **App.js** file, import the VideoPlayer component and use the component to embed the video on the page. You can specify the width and height of the player by passing the dimensions through `props`. Control the player by specifying `controls` in the `<video>` element. Learn about all the options and features of the Video Player in the [guide](cloudinary_video_player) and [reference](video_player_api_reference). 
|

You can find the code used in this video tutorial in [GitHub](https://github.com/cloudinary-community/cloudinary-examples/tree/main/examples/react-video-player).

## 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](https://console.cloudinary.com/app/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:

```html
<iframe
src="https://player.cloudinary.com/embed/?cloud_name=demo&public_id=elephants"
width="640"
height="360"
style="height: auto; width: 100%; aspect-ratio: 640 / 360;"
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:

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

{table:class=param-table}Param | Type | Description
---|---|---
cloud_name | String | The cloud name for your Cloudinary product environment.
public_id | String | The Cloudinary unique identifier for the video.

#### Optional parameters

{table:class=param-table}Param | Type | Description
---|---|---
cloudinary | Object | The Cloudinary product environment-specific [configuration](cloudinary_sdks#configuration_parameters) parameters to apply.
player | Object | The configuration for the player itself, including the [player visuals](video_player_api_reference#player_visuals) and [behavior](video_player_api_reference#player_behavior). 
source | Object | The configuration to apply to the [video source](video_player_api_reference#video_config).
vpv | String | The [version](https://github.com/cloudinary/cloudinary-video-player/releases) 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:

```js
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](https://www.npmjs.com/package/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:

```js
const config = { cloud_name: "demo", public_id: "elephants", cloudinary: { cname: "myCname" }, player: { loop: true }, source: { source_types: ['mp4/h265', 'mp4'], transformation: {quality: 'auto'}}};
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&source%5Btransformation%5D%5B1%5D%5Bquality%5D=auto`

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

```html
<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&source%5Btransformation%5D%5B1%5D%5Bquality%5D=auto'
></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:

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

#### Video tutorial: Embed the Video Player in HTML

Watch this video tutorial to learn how to embed the Video Player in an HTML document or app:

  This video is brought to you by Cloudinary's video player - embed your own!Use the controls to set the playback speed, navigate to chapters of interest and select subtitles in your preferred language.

#### Tutorial contents This tutorial presents the following topics. Click a timestamp to jump to that part of the video.
#### Introduction to the Cloudinary Video Player
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=0 :sec=00 :player=cld} | The [Cloudinary Video Player](cloudinary_video_player) provides a powerful way to deliver your videos in a customized way. You can embed the player in any app using the cloud-hosted player.
|

#### Add the Video Player manually
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=0 :sec=15 :player=cld} | Build your cloud-hosted player manually, in either an HTML document or, for example, a React app. Add a new `iframe` with `https://player.cloudinary.com/embed/?<parameters>` as the source, with two required parameters: your `cloud_name`, which you can find on the [Dashboard](https://console.cloudinary.com/app/home/dashboard) of the Console UI, and the `public_id` of the video in your product environment that you want to display.
|

```
<iframe src="https://player.cloudinary.com/embed/?cloud_name=colbycloud-examples&public_id=videos/guitar" />
```

> **NOTE**: Make sure to use your own cloud name instead of `colbycloud-examples` and a public ID for a video in your product environment instead of `videos/guitar`.

#### Recommended settings
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=1 :sec=16 :player=cld} | To make your video look even better, add the following recommended settings, changing the width and height to fit your design:
|

```
<iframe 
    src="https://player.clouydinary.com/embed/?cloud_name=<CLOUD_NAME>&public_id=<PUBLIC_ID>" />
    width="640"
    height="360"
    style="height: auto; width: 100%; aspect-ratio: 640/360;"
    allow="autoplay; fullscreen; encrypted-media; picture-in-picture"
    allowfullscreen
    frameborder="0"
/>
```

#### Add your video using the Video Player Studio
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=1 :sec=38 :player=cld} | Even easier, use the [Video Player Studio](https://studio.cloudinary.com) to build your customized cloud-hosted player. In the Video Player Studio UI, update the **Video Source** with your cloud name and the public ID of the video you'd like to display, and  customize by specifying a **Poster** image, changing the **Theme** and more.

#### Using the generated code snippet
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=media :min=1 :sec=53 :player=cld} | The Video Player Studio generates the code that you can use to embed your customized Video Player in your HTML document or app. Once you're done customizing, copy either the JavaScript sippet, or the embed snippet and paste the generated `iframe` into your application. In an application such as React, you may have to make the `style` parameter an object:
|

```
<iframe 
    src="https://player.clouydinary.com/embed/?cloud_name=<CLOUD_NAME>&public_id=<PUBLIC_ID>" />
    width="640"
    height="360"
    style={
        height: 'auto', 
        width: '100%', 
        aspect-ratio: '640/360'
    }
    allow="autoplay; fullscreen; encrypted-media; picture-in-picture"
    allowfullscreen
    frameborder="0"
/>
```

## 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**: 

    ```js
    vplayer.volume(0.75)
    ```

* **Mute the player**:  
    
     ```js
     vplayer.mute()
       ```

* **Jump to the middle of a video**:   

    ```js
    vlength=vplayer.duration()
    middle=vlength/2
    vplayer.currentTime(middle)
    ```

#### 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](https://demo.cloudinary.com/video_player/code_samples).

For details and code examples for all available video player operations, see the [video player methods](video_player_api_reference#instance_methods) and [playlist operations](video_player_api_reference#playlist_operations) in the _Video Player API Reference_.

## Asset-saved settings

Every video asset has player settings configured through the [Video Player Studio](video_player_studio), the [Video Config API](video_config_reference), or the standard Video Player defaults. By default, the Video Player automatically retrieves and applies these settings when you play the video. If you haven't configured any custom settings for a video, the player uses the standard Video Player defaults.

> **INFO**:
>
> * To use asset-saved settings in your code, you need to use the `player` method (instead of `videoPlayer`), which returns a promise.

> * Asset-saved settings require Video Player version 3.6.0 or later.

> * You can also save your configured settings as a reusable [player profile](#player_profiles).

### Using asset-saved settings

Every video asset has saved player settings (either custom or default), and the player automatically retrieves them. Because this process requires an asynchronous request, you must use the `player` method and handle it as a promise.

The simplest approach is to specify the video using `publicId` during initialization:

```js
const player = await cloudinary.player('example-player', {
  cloudName: 'mycloud',
  publicId: 'my-configured-video'
});
```

The player retrieves the saved settings for `my-configured-video` (such as appearance, controls, or poster options) and applies them automatically.

You can also use `.then()` instead of `await`:

```js
cloudinary.player('example-player', {
  cloudName: 'mycloud',
  publicId: 'my-configured-video'
}).then(player => {
  // Player is ready with saved settings applied
});
```

If you need to set the video source after initialization, resolve the promise first using `await`:

```js
const player = await cloudinary.player('example-player', {
  cloudName: 'mycloud',
});

player.source('my-configured-video');
```

### Overriding asset-saved settings

You can override specific asset-saved settings by defining them in your JavaScript code when initializing the player. Instance-level configurations always take precedence over asset-saved settings.

```js
const player = await cloudinary.player('example-player', {
  cloudName: 'mycloud',
  // These settings override any matching asset-saved settings
  colors: {
    base: '#1532a8'
  },
  controls: true,
});

player.source('my-configured-video');
```

### Managing video settings via the API

In addition to using the [Video Player Studio](video_player_studio) UI, you can programmatically manage per-video player configurations using the [Video Config REST API](video_config_reference). This lets you automate configuration workflows or build custom tooling.

The API uses [Basic Authentication](solution_overview#account_and_api_setup) with your Cloudinary API Key and API Secret.

#### Getting a video's player configuration

Retrieve the current player configuration for a specific video asset:

```bash
curl https://api.cloudinary.com/v2/video/<CLOUD_NAME>/player/config/video/<VIDEO_ASSET_ID> \
  -u <API_KEY>:<API_SECRET>
```

Sample response:

```json
{
  "request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
  "data": {
    "playerOptions": {
      "controls": true,
      "loop": true,
      "colors": {
        "base": "#1532a8"
      }
    },
    "sourceOptions": {
      "sourceTypes": ["hls"],
      "textTracks": {
        "subtitles": {
          "label": "English",
          "language": "en",
          "default": true
        }
      }
    }
  }
}
```

> **INFO**: If no custom configuration has been saved for the video, the response returns empty `playerOptions` and `sourceOptions` objects.

#### Creating or updating a video's player configuration

Use a PUT request to create or replace the player configuration for a specific video:

```bash
curl -X PUT \
  https://api.cloudinary.com/v2/video/<CLOUD_NAME>/player/config/video/<VIDEO_ASSET_ID> \
  -u <API_KEY>:<API_SECRET> \
  -H "Content-Type: application/json" \
  -d '{
    "playerOptions": {
      "controls": true,
      "loop": true,
      "autoplay": "on-scroll",
      "colors": {
        "base": "#1532a8",
        "accent": "#FF9B00",
        "text": "#FFFFFF"
      }
    },
    "sourceOptions": {
      "sourceTypes": ["hls"]
    }
  }'
```

> **NOTE**: PUT replaces the entire configuration. To update specific fields, first retrieve the current configuration with GET, merge your changes, and then PUT the full updated object.

The `playerOptions` and `sourceOptions` objects accept the same configuration keys as the [Video Player constructor](video_player_api_reference#constructor_parameters) and [source method options](video_player_api_reference#options) respectively. For the full endpoint specification, see the [Video Config API reference](video_config_reference).

#### Configuration precedence

When multiple configuration sources are present, the Video Player applies them in the following order (highest priority first):

1. **Instance-level code**: Settings defined in your JavaScript when initializing the player.
2. **Player profile**: Settings from a [profile](#player_profiles), if one is specified.
3. **Asset-saved settings**: Per-video settings saved via the Video Player Studio or the Video Config API.
4. **Defaults**: Standard Video Player defaults.

## Player profiles

Video player profiles provide a mechanism to define and save your video player [configuration](video_player_customization) to your Cloudinary account and then reference this profile as part of your video player setup.

You can use profiles to apply a consistent configuration across multiple videos or update multiple video assets at once. If you specify a profile, it overrides the video's asset-saved settings. This allows you to easily make changes via the UI and apply those changes to all instances without having to deploy your code.

> **INFO**:
>
> * Video player profiles require version 2.1.1 or later of the video player.

> * To use profiles in your code, you need to use a newly added method called `player` (instead of `videoPlayer` as shown throughout the rest of the guide). See [using profiles](#using_profiles) for more information.

> **TIP**: You can create profiles using the [Video Player Profiles](https://console.cloudinary.com/app/video/player-profiles) page or the [Video Player Studio](video_player_studio).

### Creating profiles

You can create and manage Video Player profiles using the [Video Player Profiles](https://console.cloudinary.com/app/video/player-profiles) page in the Cloudinary Console or programmatically via the [Player Profiles API](video_player_profiles_reference). We currently offer a set of system profiles that are pre-configured for certain use-cases. You can duplicate these to use as a starting point, or alternatively you can create your own from scratch.

  
  
    
    
  
  
  
    
    
  

> **NOTE**: The Video Player Studio enables configuration of the player using a visual interface. Some of the configuration options aren't available in the studio. In these cases, you can use the "Advanced config editing" button to edit the player configuration JSON.

![Video player studio advanced config editing](https://res.cloudinary.com/cloudinary/image/upload/f_auto/q_auto/bo_1px_solid_gray/docs/vp_studio_advanced_edit "thumb: w_400,dpr_2, width: 400, popup:true")

### Using profiles

To use a profile for your player configuration, you need to specify it when creating your player instance. 
In order for the profile details to be properly loaded, you need to use a newly added method called `player` (instead of `videoPlayer` as shown throughout the rest of the guide), which returns a promise instead of an instance of the player. This prevents any player instance methods, such as `source`, being set before the profile is loaded. To use any of these instance methods, you must resolve the promise, for example by asynchronously initializing the player using `await`:

```js
const playerWithProfile = await cloudinary.player('example-player', {
  cloudName: 'prod',
  profile: 'myProfile',
});

playerWithProfile.source('elephants');

```

Alternatively, you can set the player video using the `publicId` during the initialization:

```js
const playerWithProfile = cloudinary.player('example-player', {
  cloudName: 'prod',
  profile: 'myProfile',
  publicId: 'elephants'
});

```

You can also override any configuration specified in your profile by including the relevant configuration as part of initializing the player. You might use this to ensure certain aspects of your player can't be changed as part of the profile. Here's an example:

```js
const playerWithProfile = cloudinary.player('example-player', {
  cloudName: 'prod',
  profile: 'myProfile',
  publicId: 'elephants',
  colors: {
    base: '#1532a8'
  },
  controls: true,

});

```

### Updating profiles

To make changes to your profiles when they are already in use, you can update and save the profile using the [Video Player Studio](video_player_studio) by selecting **Save settings as profile** and then **Override an existing profile**, using the [Video Player Profiles](https://console.cloudinary.com/app/video/player-profiles) page in the Console, or programmatically via the [Player Profiles API](video_player_profiles_reference). Once you have saved any profile changes, the process of clearing the cache will begin. It can take a few minutes before your changes are reflected in your player.

> **TIP**: For testing purposes, you may want to duplicate your production profile to a test profile that is referenced across any testing environments you may be using. This will allow you to update and verify the test profile is working as expected before making changes to your production profile.

## 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](video_player_api_reference) 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](https://cloudinary.com/pricing)), you will need to ensure that you eagerly generate the right URLs to match your configuration.

For example, the default [sourceTypes](video_player_api_reference#video_config) 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](eager_and_incoming_transformations#eager_transformations) the URLs you require. The same principle applies if you use any transformations on your videos.

### Full example

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

```html

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

**Video player JavaScript configuration:**

```js
const cld = cloudinary.videoPlayer('demo-player',{ 
  cloudName: "demo", 
  secure: true,
  sourceTypes: ['webm/vp9','mp4/h265','mp4'],
  transformation: {
    effect: "vignette",
    border: "5px_solid_black"
  }
});
cld.source("my-video");
```

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:

* `https://res.cloudinary.com/demo/video/upload/bo_5px_solid_black,e_vignette/vc_vp9/my-video.webm`
* `https://res.cloudinary.com/demo/video/upload/bo_5px_solid_black,e_vignette/vc_h265/my-video.mp4`
* `https://res.cloudinary.com/demo/video/upload/bo_5px_solid_black,e_vignette/my-video.mp4`

> **NOTE**: The transformations defined in your video player configuration are alphabetized in the delivery URLs. Transforming eagerly using our SDKs, as shown below, will also alphabetize the transformations to ensure they match. Any chained transformations will be created in the order they are chained, so you should ensure you define these in the same order for both. 

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:

```multi
|ruby 
Cloudinary::Uploader.upload(my-video, 
  resource_type: "video",
  eager_async: true,
  eager_notification_url: "https://mysite.example.com/eager_endpoint",
  eager: [
    { 
      format: "webm",
      transformation: [
        { effect: "vignette", border: "5px_solid_black" },
        { video_codec: "vp9" }
      ]
    },
    { 
      format: "mp4",
      transformation: [
        { effect: "vignette", border: "5px_solid_black" },
        { video_codec: "h265" }
      ]
    },
    { 
      format: "mp4",
      transformation: { effect: "vignette", border: "5px_solid_black" }
    }
  ]
)
|php_2
$cloudinary->uploadApi()->upload(my-video, [
  'resource_type' => 'video',
  'eager' => [
    [
      ['format' => 'webm']
      ['effect' => 'vignette', 'border' => '5px_solid_black'],
      ['video_codec' => 'vp9']
    ],
    [
      ['format' => 'mp4']
      ['effect' => 'vignette', 'border' => '5px_solid_black'],
      ['video_codec' => 'h265']
    ],  
    [
      ['format' => 'mp4']
      ['effect' => 'vignette', 'border' => '5px_solid_black'],
    ]
  ],
  'eager_async' => true, 
  'eager_notification_url' => 'https://mysite.example.com/eager_endpoint']);

|python
cloudinary.uploader.upload(my-video, 
  resource_type = "video",
  eager = [
    {
      "format": "webm",
      "transformation": [
        {"effect": "vignette", "border":"5px_solid_black"},
        {"video_codec": "vp9"}
      ]
    },
    {
      "format": "mp4",
      "transformation": [
        {"effect": "vignette", "border":"5px_solid_black"},
        {"video_codec": "h265"}
      ]
    },
    {
      "format": "mp4",
      "transformation": {"effect":"vignette", "border":"5px_solid_black"}
    },
  ],
  eager_async = True,
  eager_notification_url = "https://mysite.example.com/eager_endpoint") 

|nodejs
cloudinary.v2.uploader
.upload(my-video, 
  { resource_type: "video",
    eager_async: true,
    eager_notification_url: "https://mysite.example.com/eager_endpoint", 
    eager: [
            { 
              format: "webm", 
              transformation: [
                {"effect": "vignette", "border":"5px_solid_black"},
                {"video_codec": "vp9"}
              ]
            },
            { 
              format: "mp4", 
              transformation: [
                {"effect": "vignette", "border":"5px_solid_black"},
                {"video_codec": "h265"}
              ]
            },
            { 
              format: "mp4", 
              transformation: {"effect": "vignette", "border":"5px_solid_black"}
            },
          ]
  })
.then(result=>console.log(result)); 
  
|java
cloudinary.uploader().upload(my-video, 
  ObjectUtils.asMap(
  "resource_type", "video",
  "eager", Arrays.asList(
    new EagerTransformation()
      .format("webm").chain()
      .effect("vignette").border("5px_solid_black").chain()
      .videoCodec("vp9"),
    new EagerTransformation()
      .format("mp4").chain()
      .effect("vignette").border("5px_solid_black").chain()
      .videoCodec("h265"),
    new EagerTransformation()
      .format("mp4").chain()
      .effect("vignette").border("5px_solid_black")
  ),        
  "eager_async", true,
  "eager_notification_url", "https://mysite.example.com/eager_endpoint"
  )
) 

|csharp
var uploadParams = new VideoUploadParams()
{
  File = new FileDescription(@"my-video"),
  Type = "upload",
  EagerTransforms = new List<Transformation>()
  {
    new EagerTransformation().SetFormat("webm").Effect("vignette").Border("5px_solid_black").Chain()
      .VideoCodec("vp9"),			
    new EagerTransformation().SetFormat("mp4").Effect("vignette").Border("5px_solid_black").Chain().
      VideoCodec("h265"),			
    new EagerTransformation().SetFormat("mp4").Effect("vignette").Border("5px_solid_black")			
  },
  EagerAsync = true,
  EagerNotificationUrl = "https://mysite.example.com/eager_endpoint"
};
var uploadResult = cloudinary.Upload(uploadParams);                         

|go
resp, err := cld.Upload.Upload(ctx, "my_video", uploader.UploadParams{
		ResourceType:         "video",
		EagerAsync:           api.Bool(true),
		EagerNotificationURL: "https://mysite.example.com/eager_endpoint",
		Eager:                "f_webm/e_vignette/bo_5px_solid_black/vc_vp9|f_mp4/bo_5px_solid_black/e_vignette/vc_h265|f_mp4/e_vignette/bo_5px_solid_black"})
```

The example code above processes the eager transformations asynchronously and sends a [notification](notifications) 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](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](upload_presets#managing_upload_presets_using_the_settings_ui) or alternatively you can do this [programmatically](upload_presets#managing_upload_presets_programmatically).

Once you have your upload preset, you can use it with your upload code as shown below.

```multi
|ruby
Cloudinary::Uploader.upload(my-video, "my-upload-preset")
|php_2
$cloudinary->uploadApi()->upload(my-video, "my-upload-preset")

|python
cloudinary.uploader.upload(my-video, "my-upload-preset")

|nodejs
cloudinary.v2.uploader.upload(my-video, "my-upload-preset");
  
|java
cloudinary.uploader().upload(my-video, "my-upload-preset");

|csharp
cloudinary.Upload(UploadParams params);  

|go
resp, err := cld.Upload.Upload(ctx, my_video, uploader.UploadParams{
    UploadPreset: "my-upload-preset");
```

> **What's Next?**:
>
> * [Customize your video player](video_player_customization)

> * [Learn more about the video effects and transformations you can apply to your videos](video_manipulation_and_delivery)

> * [Deliver your videos using HLS or DASH adaptive bitrate streaming formats](video_player_hls_dash)

> * [Define playlists and set up video recommendations](video_player_playlists_recommendations)

> * [Check out all the video player options in the Video Player API Reference](video_player_api_reference)

> * [Manage player profiles programmatically with the Player Profiles API](video_player_profiles_reference)