feat: high dynamic-range (HDR) detection

tsi · tsi · commit 3841f738224c · 2026-02-17T17:19:06.000+02:00
diff --git a/docs/es-modules/hdr.html b/docs/es-modules/hdr.html
@@ -0,0 +1,62 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Cloudinary Video Player</title>
+    <link
+      href="https://res.cloudinary.com/cloudinary-marketing/image/upload/f_auto,q_auto/c_scale,w_32,e_hue:290/creative_staging/cloudinary_internal/Website/Brand%20Updates/Favicon/cloudinary_web_favicon_192x192.png"
+      rel="icon"
+      type="image/png"
+    />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  </head>
+  <body>
+    <div class="container p-4 col-12 col-md-9 col-xl-6">
+      <nav class="nav mb-2">
+        <a href="/index.html">&#60;&#60; Back to examples index</a>
+      </nav>
+      <h1>Cloudinary Video Player</h1>
+      <h3 class="mb-4">HDR</h3>
+
+      <div class="form-check mb-2">
+        <input type="checkbox" class="form-check-input" id="hdr-toggle" checked>
+        <label class="form-check-label" for="hdr-toggle">Enable HDR</label>
+      </div>
+
+      <video
+        id="player"
+        playsinline
+        controls
+        muted
+        autoplay
+        class="cld-video-player"
+        width="500"
+      ></video>
+    </div>
+
+    <script type="module">
+      import { videoPlayer } from 'cloudinary-video-player';
+      import 'cloudinary-video-player/cld-video-player.min.css';
+
+      function loadSource(hdrEnabled) {
+        player.source('video/examples/hdr', { hdr: hdrEnabled, info: { title: hdrEnabled ? 'HDR' : 'SDR' } });
+      }
+
+      const player = videoPlayer('player', { cloudName: 'prod' });
+      loadSource(true);
+
+      document.getElementById('hdr-toggle').addEventListener('change', function () {
+        loadSource(this.checked);
+      });
+    </script>
+
+    <!-- Bootstrap -->
+    <link
+      href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css"
+      rel="stylesheet"
+      integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T"
+      crossorigin="anonymous"
+    />
+  </body>
+</html>
diff --git a/docs/es-modules/index.html b/docs/es-modules/index.html
@@ -60,6 +60,7 @@ <h3 class="mt-4">Code examples:</h3>
         <li><a href="./floating-player.html">Floating Player</a></li>
         <li><a href="./fluid.html">Fluid Layouts</a></li>
         <li><a href="./force-hls-subtitles.html">Force HLS Subtitles</a></li>
+        <li><a href="./hdr.html">HDR</a></li>
         <li><a href="./interaction-area.html">Interaction Area</a></li>
         <li><a href="./multiple-players.html">Multiple Players</a></li>
         <li><a href="./playlist.html">Playlist</a></li>
diff --git a/docs/hdr.html b/docs/hdr.html
@@ -0,0 +1,92 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Cloudinary Video Player</title>
+  <link href="https://res.cloudinary.com/cloudinary-marketing/image/upload/f_auto,q_auto/c_scale,w_32/v1597183771/creative_staging/cloudinary_internal/Website/Brand%20Updates/Favicon/cloudinary_web_favicon_192x192.png" rel="icon" type="image/png">
+
+  <!-- Bootstrap -->
+  <link href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
+
+  <!-- highlight.js -->
+  <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/solarized-light.min.css">
+  <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
+  <script>hljs.initHighlightingOnLoad();</script>
+
+  <!--
+    We're loading scripts & style dynamically for development/testing.
+    Real-world usage would look like this:
+
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/cloudinary-video-player/dist/cld-video-player.min.css">
+    <script src="https://cdn.jsdelivr.net/npm/cloudinary-video-player/dist/cld-video-player.min.js"></script>
+  -->
+
+  <script type="text/javascript" src="./scripts.js"></script>
+
+  <script type="text/javascript">
+    var player;
+
+    function loadSource(hdrEnabled) {
+      player.source('video/examples/hdr', { hdr: hdrEnabled, info: { title: hdrEnabled ? 'HDR' : 'SDR' } });
+    }
+
+    window.addEventListener('load', function(){
+      player = cloudinary.videoPlayer('player', { cloud_name: 'prod' });
+      loadSource(true);
+
+      document.getElementById('hdr-toggle').addEventListener('change', function() {
+        loadSource(this.checked);
+      });
+    }, false);
+  </script>
+
+</head>
+<body>
+  <div class="container p-4 col-12 col-md-9 col-xl-6">
+    <nav class="nav mb-2">
+      <a href="./index.html">&#60;&#60; Back to examples index</a>
+    </nav>
+    <h1>Cloudinary Video Player</h1>
+    <h3 class="mb-4">HDR</h3>
+
+    <div class="form-check mb-2">
+      <input type="checkbox" class="form-check-input" id="hdr-toggle" checked>
+      <label class="form-check-label" for="hdr-toggle">Enable HDR</label>
+    </div>
+
+    <video
+      id="player"
+      playsinline
+      controls
+      muted
+      autoplay
+      class="cld-video-player"
+      width="500">
+    </video>
+
+    <p class="mt-4">
+      <a href="https://cloudinary.com/documentation/cloudinary_video_player">Full documentation</a>
+    </p>
+
+    <h3 class="mt-4">Example Code:</h3>
+    <pre>
+      <code class="language-html">
+        &lt;video
+          id="player"
+          playsinline
+          controls
+          muted
+          autoplay
+          class="cld-video-player"
+          width="500"&gt;
+        &lt;/video&gt;
+      </code>
+      <code class="language-javascript">
+        player = cloudinary.videoPlayer('player', { cloud_name: 'prod' });
+        player.source('video/examples/hdr', { hdr: true, info: { title: 'HDR' } });
+      </code>
+    </pre>
+  </div>
+
+</body>
+</html>
diff --git a/docs/index.html b/docs/index.html
@@ -64,6 +64,7 @@ <h3 class="mt-4">Some code examples:</h3>
       <li><a href="./floating-player.html">Floating Player</a></li>
       <li><a href="./fluid.html">Fluid Layouts</a></li>
       <li><a href="./force-hls-subtitles-ios.html">Force HLS Subtitles</a></li>
+      <li><a href="./hdr.html">HDR</a></li>
       <li><a href="./interaction-area.html">Interaction Area</a></li>
       <li><a href="./live-streaming.html">Live Streaming</a></li>
       <li><a href="./multiple-players.html">Multiple Players</a></li>
diff --git a/src/config/configSchema.json b/src/config/configSchema.json
@@ -143,6 +143,10 @@
       "type": "boolean",
       "default": false
     },
+    "hdr": {
+      "type": "boolean",
+      "default": false
+    },
     "seekThumbnails": {
       "type": "boolean",
       "default": true
diff --git a/src/plugins/cloudinary/models/video-source/video-source.const.js b/src/plugins/cloudinary/models/video-source/video-source.const.js
@@ -3,6 +3,7 @@ export const DEFAULT_POSTER_PARAMS = { format: 'jpg', resource_type: 'video' };
 export const DEFAULT_VIDEO_PARAMS = {
   resource_type: 'video',
   type: 'upload',
+  hdr: false,
   transformation: [],
   sourceTransformation: {},
   sourceTypes: ['auto'],
diff --git a/src/plugins/cloudinary/models/video-source/video-source.js b/src/plugins/cloudinary/models/video-source/video-source.js
@@ -204,6 +204,14 @@ class VideoSource extends BaseSource {
         }
       }
 
+      // dr (dynamic range) is not yet exposed by @cloudinary/url-gen, so we use raw_transformation
+      if (this.hdr() === true && window.matchMedia && window.matchMedia('(dynamic-range: high)').matches) {
+        opts.transformation = mergeTransformations(opts.transformation, {
+          video_codec: 'h265',
+          raw_transformation: 'dr_high'
+        });
+      }
+
       const src = appendQueryParams(this.config().url(this.publicId(), opts), this.queryParams());
 
       return {
diff --git a/src/utils/get-analytics-player-options.js b/src/utils/get-analytics-player-options.js
@@ -30,6 +30,7 @@ const getSourceOptions = (sourceOptions = {}) => ({
   })(),
   visualSearch: sourceOptions.visualSearch,
   download: hasConfig(sourceOptions.download),
+  hdr: hasConfig(sourceOptions.hdr),
   recommendations: sourceOptions.recommendations && sourceOptions.recommendations.length,
   ...(hasConfig(sourceOptions.adaptiveStreaming) ? {
     abrStrategy: sourceOptions?.adaptiveStreaming?.strategy === defaults.adaptiveStreaming.strategy ? undefined : sourceOptions?.adaptiveStreaming?.strategy,
diff --git a/src/validators/validators.js b/src/validators/validators.js
@@ -85,6 +85,7 @@ export const playerValidators = {
 
 export const sourceValidators = {
   raw_transformation: validator.isString,
+  hdr: validator.isBoolean,
   resourceType: validator.isString,
   shoppable: validator.isPlainObject,
   chapters: validator.or(validator.isBoolean, validator.isPlainObject),
diff --git a/src/video-player.const.js b/src/video-player.const.js
@@ -7,6 +7,7 @@ export const SOURCE_PARAMS = [
   'cloudinaryConfig',
   'description',
   'download',
+  'hdr',
   'info',
   'interactionAreas',
   'poster',
diff --git a/test/e2e/specs/ESM/esmHdrPage.spec.ts b/test/e2e/specs/ESM/esmHdrPage.spec.ts
@@ -0,0 +1,12 @@
+import { vpTest } from '../../fixtures/vpTest';
+import { ExampleLinkName } from '../../testData/ExampleLinkNames';
+import { testHdrPageVideoIsPlaying } from '../commonSpecs/hdrPageVideoPlaying';
+import { getEsmLinkByName } from '../../testData/esmPageLinksData';
+import { ESM_URL } from '../../testData/esmUrl';
+
+const link = getEsmLinkByName(ExampleLinkName.HDR);
+
+vpTest(`Test if video on ESM HDR page is playing as expected`, async ({ page, pomPages }) => {
+    await page.goto(ESM_URL);
+    await testHdrPageVideoIsPlaying(page, pomPages, link);
+});
diff --git a/test/e2e/specs/NonESM/hdrPage.spec.ts b/test/e2e/specs/NonESM/hdrPage.spec.ts
@@ -0,0 +1,10 @@
+import { vpTest } from '../../fixtures/vpTest';
+import { getLinkByName } from '../../testData/pageLinksData';
+import { ExampleLinkName } from '../../testData/ExampleLinkNames';
+import { testHdrPageVideoIsPlaying } from '../commonSpecs/hdrPageVideoPlaying';
+
+const link = getLinkByName(ExampleLinkName.HDR);
+
+vpTest(`Test if video on HDR page is playing as expected`, async ({ page, pomPages }) => {
+    await testHdrPageVideoIsPlaying(page, pomPages, link);
+});
diff --git a/test/e2e/specs/commonSpecs/hdrPageVideoPlaying.ts b/test/e2e/specs/commonSpecs/hdrPageVideoPlaying.ts
@@ -0,0 +1,14 @@
+import { Page, test } from '@playwright/test';
+import { waitForPageToLoadWithTimeout } from '../../src/helpers/waitForPageToLoadWithTimeout';
+import PageManager from '../../src/pom/PageManager';
+import { ExampleLinkType } from '../../types/exampleLinkType';
+
+export async function testHdrPageVideoIsPlaying(page: Page, pomPages: PageManager, link: ExampleLinkType) {
+    await test.step('Navigate to HDR page by clicking on link', async () => {
+        await pomPages.mainPage.clickLinkByName(link.name);
+        await waitForPageToLoadWithTimeout(page, 5000);
+    });
+    await test.step('Validating that HDR video is playing', async () => {
+        await pomPages.hdrPage.hdrVideoComponent.validateVideoIsPlaying(true);
+    });
+}
diff --git a/test/e2e/src/pom/PageManager.ts b/test/e2e/src/pom/PageManager.ts
@@ -15,6 +15,7 @@ import { DisplayConfigurationsPage } from './displayConfigurationsPage';
 import { FloatingPlayerPage } from './floatingPlayerPgae';
 import { FluidLayoutsPage } from './fluidLayoutsPage';
 import { ForceHlsSubtitlesPage } from './forceHlsSubtitlesPage';
+import { HdrPage } from './hdrPage';
 import { MultiplePlayersPage } from './multiplePlayersPage';
 import { PlaylistPage } from './playlistPage';
 import { PlaylistByTagPage } from './playlistByTagPage';
@@ -142,6 +143,10 @@ export class PageManager {
         return this.getPage(ForceHlsSubtitlesPage);
     }
 
+    public get hdrPage(): HdrPage {
+        return this.getPage(HdrPage);
+    }
+
     public get multiplePlayersPage(): MultiplePlayersPage {
         return this.getPage(MultiplePlayersPage);
     }
diff --git a/test/e2e/src/pom/hdrPage.ts b/test/e2e/src/pom/hdrPage.ts
@@ -0,0 +1,17 @@
+import { Page } from '@playwright/test';
+import { VideoComponent } from '../../components/videoComponent';
+import { BasePage } from './BasePage';
+
+const HDR_PAGE_VIDEO_SELECTOR = '//*[@id="player_html5_api"]';
+
+/**
+ * Video player examples HDR page object
+ */
+export class HdrPage extends BasePage {
+    public hdrVideoComponent: VideoComponent;
+
+    constructor(page: Page) {
+        super(page);
+        this.hdrVideoComponent = new VideoComponent(page, HDR_PAGE_VIDEO_SELECTOR);
+    }
+}
diff --git a/test/e2e/testData/ExampleLinkNames.ts b/test/e2e/testData/ExampleLinkNames.ts
@@ -19,6 +19,7 @@ export enum ExampleLinkName {
     FloatingPlayer = 'Floating Player',
     FluidLayouts = 'Fluid Layouts',
     ForceHLSSubtitles = 'Force HLS Subtitles',
+    HDR = 'HDR',
     InteractionArea = 'Interaction Area',
     MultiplePlayers = 'Multiple Players',
     Playlist = 'Playlist',
diff --git a/test/e2e/testData/esmPageLinksData.ts b/test/e2e/testData/esmPageLinksData.ts
@@ -22,6 +22,7 @@ export const ESM_LINKS: ExampleLinkType[] = [
     { name: ExampleLinkName.FloatingPlayer, endpoint: 'floating-player' },
     { name: ExampleLinkName.FluidLayouts, endpoint: 'fluid' },
     { name: ExampleLinkName.ForceHLSSubtitles, endpoint: 'force-hls-subtitles' },
+    { name: ExampleLinkName.HDR, endpoint: 'hdr' },
     { name: ExampleLinkName.InteractionArea, endpoint: 'interaction-area' },
     { name: ExampleLinkName.MultiplePlayers, endpoint: 'multiple-players' },
     { name: ExampleLinkName.Playlist, endpoint: 'playlist' },
diff --git a/test/e2e/testData/pageLinksData.ts b/test/e2e/testData/pageLinksData.ts
@@ -22,6 +22,7 @@ export const LINKS: ExampleLinkType[] = [
     { name: ExampleLinkName.FloatingPlayer, endpoint: 'floating-player.html' },
     { name: ExampleLinkName.FluidLayouts, endpoint: 'fluid.html' },
     { name: ExampleLinkName.ForceHLSSubtitles, endpoint: 'force-hls-subtitles-ios.html' },
+    { name: ExampleLinkName.HDR, endpoint: 'hdr.html' },
     { name: ExampleLinkName.InteractionArea, endpoint: 'interaction-area.html' },
     { name: ExampleLinkName.MultiplePlayers, endpoint: 'multiple-players.html' },
     { name: ExampleLinkName.Playlist, endpoint: 'playlist.html' },
diff --git a/test/unit/videoSource.test.js b/test/unit/videoSource.test.js
@@ -60,6 +60,46 @@ describe('video source tests', () => {
     expect(srcs[0]).toContain('t_test');
   });
 });
+
+describe('HDR option tests', () => {
+  let matchMediaSpy;
+
+  afterEach(() => {
+    matchMediaSpy?.mockRestore();
+  });
+
+  it('adds vc_h265 and dr_high when hdr: true and device supports HDR', () => {
+    matchMediaSpy = vi.spyOn(window, 'matchMedia').mockReturnValue({ matches: true });
+    const source = new VideoSource('sea_turtle', { cloudinaryConfig: cld, hdr: true });
+    source.sourceTypes(['hls']);
+    const srcs = source.generateSources().map(s => s.src);
+    expect(srcs[0]).toContain('vc_h265');
+    expect(srcs[0]).toContain('dr_high');
+  });
+
+  it('does not add dr_high when hdr: true but device does not support HDR', () => {
+    matchMediaSpy = vi.spyOn(window, 'matchMedia').mockReturnValue({ matches: false });
+    const source = new VideoSource('sea_turtle', { cloudinaryConfig: cld, hdr: true });
+    source.sourceTypes(['hls']);
+    const srcs = source.generateSources().map(s => s.src);
+    expect(srcs[0]).not.toContain('dr_high');
+  });
+
+  it('does not add HDR transformation when hdr: false', () => {
+    const source = new VideoSource('sea_turtle', { cloudinaryConfig: cld, hdr: false });
+    source.sourceTypes(['hls']);
+    const srcs = source.generateSources().map(s => s.src);
+    expect(srcs[0]).not.toContain('dr_high');
+  });
+
+  it('does not add HDR transformation when hdr is not set (default)', () => {
+    const source = new VideoSource('sea_turtle', { cloudinaryConfig: cld });
+    source.sourceTypes(['hls']);
+    const srcs = source.generateSources().map(s => s.src);
+    expect(srcs[0]).not.toContain('dr_high');
+  });
+});
+
 describe('Adaptive source type tests', () => {
   it('Test hls no codec', () => {
     let sourceDef = {

Original file line number	Diff line number	Diff line change
`@@ -204,6 +204,14 @@ class VideoSource extends BaseSource {`
`204`	`204`	`}`
`205`	`205`	`}`
`206`	`206`
	`207`	`+ // dr (dynamic range) is not yet exposed by @cloudinary/url-gen, so we use raw_transformation`
	`208`	`+ if (this.hdr() === true && window.matchMedia && window.matchMedia('(dynamic-range: high)').matches) {`
	`209`	`+ opts.transformation = mergeTransformations(opts.transformation, {`
	`210`	`+ video_codec: 'h265',`
	`211`	`+ raw_transformation: 'dr_high'`
	`212`	`+ });`
	`213`	`+ }`
	`214`	`+`
`207`	`215`	`const src = appendQueryParams(this.config().url(this.publicId(), opts), this.queryParams());`
`208`	`216`
`209`	`217`	`return {`