feat: Add getVideoPlaybackQuality API (#4286)

Provides a tech getter for getVideoPlaybackQuality as specified by the W3C's Media Playback Quality API: https://wicg.github.io/media-playback-quality/.

Author: gesinger

package.json

@@ -41,7 +41,7 @@
     "tsml": "1.0.1",
     "videojs-font": "2.0.0",
     "videojs-ie8": "1.1.2",
-    "videojs-swf": "5.3.0",
+    "videojs-swf": "5.4.0",
     "videojs-vtt.js": "0.12.3",
     "xhr": "2.2.2"
   },

src/js/player.js

@@ -2993,6 +2993,20 @@ class Player extends Component {
     }
   }
 
+  /**
+   * Gets available media playback quality metrics as specified by the W3C's Media
+   * Playback Quality API.
+   *
+   * @see [Spec]{@link https://wicg.github.io/media-playback-quality}
+   *
+   * @return {Object|undefined}
+   *         An object with supported media playback quality metrics or undefined if there
+   *         is no tech or the tech does not support it.
+   */
+  getVideoPlaybackQuality() {
+    return this.techGet_('getVideoPlaybackQuality');
+  }
+
   /**
    * Get video width
    *

src/js/tech/flash.js

@@ -341,6 +341,29 @@ class Flash extends Tech {
     return false;
   }
 
+  /**
+   * Gets available media playback quality metrics as specified by the W3C's Media
+   * Playback Quality API.
+   *
+   * @see [Spec]{@link https://wicg.github.io/media-playback-quality}
+   *
+   * @return {Object}
+   *         An object with supported media playback quality metrics
+   */
+  getVideoPlaybackQuality() {
+    const videoPlaybackQuality = this.el_.vjs_getProperty('getVideoPlaybackQuality');
+
+    if (window.performance && typeof window.performance.now === 'function') {
+      videoPlaybackQuality.creationTime = window.performance.now();
+    } else if (window.performance &&
+               window.performance.timing &&
+               typeof window.performance.timing.navigationStart === 'number') {
+      videoPlaybackQuality.creationTime =
+        window.Date.now() - window.performance.timing.navigationStart;
+    }
+
+    return videoPlaybackQuality;
+  }
 }
 
 // Create setters and getters for attributes

src/js/tech/html5.js

@@ -794,6 +794,40 @@ class Html5 extends Tech {
       }
     }
   }
+
+  /**
+   * Gets available media playback quality metrics as specified by the W3C's Media
+   * Playback Quality API.
+   *
+   * @see [Spec]{@link https://wicg.github.io/media-playback-quality}
+   *
+   * @return {Object}
+   *         An object with supported media playback quality metrics
+   */
+  getVideoPlaybackQuality() {
+    if (typeof this.el().getVideoPlaybackQuality === 'function') {
+      return this.el().getVideoPlaybackQuality();
+    }
+
+    const videoPlaybackQuality = {};
+
+    if (typeof this.el().webkitDroppedFrameCount !== 'undefined' &&
+        typeof this.el().webkitDecodedFrameCount !== 'undefined') {
+      videoPlaybackQuality.droppedVideoFrames = this.el().webkitDroppedFrameCount;
+      videoPlaybackQuality.totalVideoFrames = this.el().webkitDecodedFrameCount;
+    }
+
+    if (window.performance && typeof window.performance.now === 'function') {
+      videoPlaybackQuality.creationTime = window.performance.now();
+    } else if (window.performance &&
+               window.performance.timing &&
+               typeof window.performance.timing.navigationStart === 'number') {
+      videoPlaybackQuality.creationTime =
+        window.Date.now() - window.performance.timing.navigationStart;
+    }
+
+    return videoPlaybackQuality;
+  }
 }
 
 /* HTML5 Support Testing ---------------------------------------------------- */

src/js/tech/tech.js

@@ -805,6 +805,21 @@ class Tech extends Component {
     this.autoRemoteTextTracks_.removeTrack_(track);
   }
 
+  /**
+   * Gets available media playback quality metrics as specified by the W3C's Media
+   * Playback Quality API.
+   *
+   * @see [Spec]{@link https://wicg.github.io/media-playback-quality}
+   *
+   * @return {Object}
+   *         An object with supported media playback quality metrics
+   *
+   * @abstract
+   */
+  getVideoPlaybackQuality() {
+    return {};
+  }
+
   /**
    * A method to set a poster from a `Tech`.
    *

test/api/api.js

@@ -59,6 +59,7 @@ QUnit.test('should be able to access expected player API methods', function(asse
   assert.ok(player.userActive, 'userActive exists');
   assert.ok(player.usingNativeControls, 'usingNativeControls exists');
   assert.ok(player.isFullscreen, 'isFullscreen exists');
+  assert.ok(player.getVideoPlaybackQuality, 'getVideoPlaybackQuality exists');
 
   // Track methods
   assert.ok(player.audioTracks, 'audioTracks exists');

test/unit/tech/flash.test.js

@@ -2,6 +2,7 @@
 import Flash from '../../../src/js/tech/flash.js';
 import { createTimeRange } from '../../../src/js/utils/time-ranges.js';
 import document from 'global/document';
+import window from 'global/window';
 import sinon from 'sinon';
 
 // fake out the <object> interaction but leave all the other logic intact
@@ -261,3 +262,81 @@ QUnit.test('duration returns NaN, Infinity or duration according to the HTML sta
               'duration returns duration property when readyState' +
               ' and duration property are both higher than 0');
 });
+
+QUnit.test('getVideoPlaybackQuality API exists', function(assert) {
+  const propertyCalls = [];
+  const videoPlaybackQuality = { test: 'test' };
+  const mockFlash = {
+    el_: {
+      /* eslint-disable camelcase */
+      vjs_getProperty(attr) {
+        propertyCalls.push(attr);
+        return videoPlaybackQuality;
+      }
+      /* eslint-enable camelcase */
+    }
+  };
+
+  assert.equal(typeof Flash.prototype.getVideoPlaybackQuality,
+               'function',
+               'getVideoPlaybackQuality is a function');
+  assert.deepEqual(Flash.prototype.getVideoPlaybackQuality.call(mockFlash),
+                   videoPlaybackQuality,
+                   'called to get property from flash');
+  assert.equal(propertyCalls.length, 1, 'only one property call');
+  assert.equal(propertyCalls[0],
+               'getVideoPlaybackQuality',
+               'called for getVideoPlaybackQuality');
+});
+
+QUnit.test('getVideoPlaybackQuality uses best available creationTime', function(assert) {
+  const origPerformance = window.performance;
+  const origDate = window.Date;
+  const videoPlaybackQuality = {};
+  const mockFlash = {
+    el_: {
+      /* eslint-disable camelcase */
+      vjs_getProperty(attr) {
+        return videoPlaybackQuality;
+      }
+      /* eslint-enable camelcase */
+    }
+  };
+
+  window.performance = void 0;
+  assert.notOk(Flash.prototype.getVideoPlaybackQuality.call(mockFlash).creationTime,
+               'no creationTime when no performance API available');
+
+  window.performance = {
+    timing: {}
+  };
+  assert.notOk(Flash.prototype.getVideoPlaybackQuality.call(mockFlash).creationTime,
+               'no creationTime when performance API insufficient');
+
+  window.performance = {
+    now: () => 4
+  };
+  assert.equal(Flash.prototype.getVideoPlaybackQuality.call(mockFlash).creationTime,
+               4,
+               'creationTime is performance.now when available');
+
+  window.Date = {
+    now: () => 10
+  };
+  window.performance = {
+    timing: {
+      navigationStart: 3
+    }
+  };
+  assert.equal(Flash.prototype.getVideoPlaybackQuality.call(mockFlash).creationTime,
+               7,
+               'creationTime uses Date.now() - navigationStart when available');
+
+  window.performance.now = () => 4;
+  assert.equal(Flash.prototype.getVideoPlaybackQuality.call(mockFlash).creationTime,
+               4,
+               'creationTime prioritizes performance.now when available');
+
+  window.Date = origDate;
+  window.performance = origPerformance;
+});

test/unit/tech/html5.test.js

@@ -667,3 +667,83 @@ test('When Android Chrome reports Infinity duration with currentTime 0, return N
   browser.IS_CHROME = oldIsChrome;
   tech.el_ = oldEl;
 });
+
+QUnit.test('supports getting available media playback quality metrics', function(assert) {
+  const origPerformance = window.performance;
+  const origDate = window.Date;
+  const oldEl = tech.el_;
+  const videoPlaybackQuality = {
+    creationTime: 1,
+    corruptedVideoFrames: 2,
+    droppedVideoFrames: 3,
+    totalVideoFrames: 5
+  };
+
+  tech.el_ = {
+    getVideoPlaybackQuality: () => videoPlaybackQuality
+  };
+  assert.deepEqual(tech.getVideoPlaybackQuality(),
+                   videoPlaybackQuality,
+                   'uses native implementation when supported');
+
+  tech.el_ = {
+    webkitDroppedFrameCount: 1,
+    webkitDecodedFrameCount: 2
+  };
+  window.performance = {
+    now: () => 4
+  };
+  assert.deepEqual(tech.getVideoPlaybackQuality(),
+                   { droppedVideoFrames: 1, totalVideoFrames: 2, creationTime: 4 },
+                   'uses webkit prefixed metrics and performance.now when supported');
+
+  tech.el_ = {
+    webkitDroppedFrameCount: 1,
+    webkitDecodedFrameCount: 2
+  };
+  window.Date = {
+    now: () => 10
+  };
+  window.performance = {
+    timing: {
+      navigationStart: 3
+    }
+  };
+  assert.deepEqual(tech.getVideoPlaybackQuality(),
+                   { droppedVideoFrames: 1, totalVideoFrames: 2, creationTime: 7 },
+                   'uses webkit prefixed metrics and Date.now() - navigationStart when ' +
+                   'supported');
+
+  tech.el_ = {};
+  window.performance = void 0;
+  assert.deepEqual(tech.getVideoPlaybackQuality(), {}, 'empty object when not supported');
+
+  window.performance = {
+    now: () => 5
+  };
+  assert.deepEqual(tech.getVideoPlaybackQuality(),
+                   { creationTime: 5 },
+                   'only creation time when it\'s the only piece available');
+
+  window.performance = {
+    timing: {
+      navigationStart: 3
+    }
+  };
+  assert.deepEqual(tech.getVideoPlaybackQuality(),
+                   { creationTime: 7 },
+                   'only creation time when it\'s the only piece available');
+
+  tech.el_ = {
+    getVideoPlaybackQuality: () => videoPlaybackQuality,
+    webkitDroppedFrameCount: 1,
+    webkitDecodedFrameCount: 2
+  };
+  assert.deepEqual(tech.getVideoPlaybackQuality(),
+                   videoPlaybackQuality,
+                   'prefers native implementation when supported');
+
+  tech.el_ = oldEl;
+  window.performance = origPerformance;
+  window.Date = origDate;
+});

test/unit/tech/tech.test.js

@@ -631,3 +631,9 @@ QUnit.test('setSource after previous setSource should dispose source handler onc
 
 });
 
+QUnit.test('returns an empty object for getVideoPlaybackQuality', function(assert) {
+  const tech = new Tech();
+
+  assert.deepEqual(tech.getVideoPlaybackQuality(), {}, 'returns an empty object');
+});
+