feat(player): add played(), defaultMuted(), defaultPlaybackRate() (#3845

)

Add `played()`, `defaultMuted()` and `defaultPlaybackRate()` methods to the player.

Fixes #523.

src/js/player.js

@@ -1606,6 +1606,18 @@ class Player extends Component {
     return (this.techGet_('paused') === false) ? false : true;
   }
 
+  /**
+   * Get a TimeRange object representing the current ranges of time that the user
+   * has played.
+   *
+   * @return {TimeRange}
+   *         A time range object that represents all the increments of time that have
+   *         been played.
+   */
+  played() {
+    return this.techGet_('played') || createTimeRange(0, 0);
+  }
+
   /**
    * Returns whether or not the user is "scrubbing". Scrubbing is
    * when the user has clicked the progress bar handle and is
@@ -1813,6 +1825,39 @@ class Player extends Component {
     return this.techGet_('muted') || false;
   }
 
+  /**
+   * Get the current defaultMuted state, or turn defaultMuted on or off. defaultMuted
+   * indicates the state of muted on intial playback.
+   *
+   * ```js
+   *   var myPlayer = videojs('some-player-id');
+   *
+   *   myPlayer.src("http://www.example.com/path/to/video.mp4");
+   *
+   *   // get, should be false
+   *   console.log(myPlayer.defaultMuted());
+   *   // set to true
+   *   myPlayer.defaultMuted(true);
+   *   // get should be true
+   *   console.log(myPlayer.defaultMuted());
+   * ```
+   *
+   * @param {boolean} [defaultMuted]
+   *        - true to mute
+   *        - false to unmute
+   *
+   * @return {boolean|Player}
+   *         - true if defaultMuted is on and getting
+   *         - false if defaultMuted is off and getting
+   *         - A reference to the current player when setting
+   */
+  defaultMuted(defaultMuted) {
+    if (defaultMuted !== undefined) {
+      return this.techCall_('setDefaultMuted', defaultMuted);
+    }
+    return this.techGet_('defaultMuted') || false;
+  }
+
   /**
    * Check if current tech can support native fullscreen
    * (e.g. with built in controls like iOS, so not our flash swf)
@@ -2751,6 +2796,32 @@ class Player extends Component {
     return 1.0;
   }
 
+  /**
+   * Gets or sets the current default playback rate. A default playback rate of
+   * 1.0 represents normal speed and 0.5 would indicate half-speed playback, for instance.
+   * defaultPlaybackRate will only represent what the intial playbackRate of a video was, not
+   * not the current playbackRate.
+   *
+   * @see https://html.spec.whatwg.org/multipage/embedded-content.html#dom-media-defaultplaybackrate
+   *
+   * @param {number} [rate]
+   *       New default playback rate to set.
+   *
+   * @return {number|Player}
+   *         - The default playback rate when getting or 1.0
+   *         - the player when setting
+   */
+  defaultPlaybackRate(rate) {
+    if (rate !== undefined) {
+      return this.techCall_('setDefaultPlaybackRate', rate);
+    }
+
+    if (this.tech_ && this.tech_.featuresPlaybackRate) {
+      return this.techGet_('defaultPlaybackRate');
+    }
+    return 1.0;
+  }
+
   /**
    * Gets or sets the audio flag
    *
@@ -2957,13 +3028,6 @@ class Player extends Component {
     return this.tech_ && this.tech_.videoHeight && this.tech_.videoHeight() || 0;
   }
 
-  // Methods to add support for
-  // initialTime: function() { return this.techCall_('initialTime'); },
-  // startOffsetTime: function() { return this.techCall_('startOffsetTime'); },
-  // played: function() { return this.techCall_('played'); },
-  // defaultPlaybackRate: function() { return this.techCall_('defaultPlaybackRate'); },
-  // defaultMuted: function() { return this.techCall_('defaultMuted'); }
-
   /**
    * The player's language code
    * NOTE: The language should be set in the player options if you want the

src/js/tech/flash.js

@@ -344,7 +344,7 @@ class Flash extends Tech {
 
 // Create setters and getters for attributes
 const _api = Flash.prototype;
-const _readWrite = 'rtmpConnection,rtmpStream,preload,defaultPlaybackRate,playbackRate,autoplay,loop,mediaGroup,controller,controls,volume,muted,defaultMuted'.split(',');
+const _readWrite = 'rtmpConnection,rtmpStream,preload,defaultPlaybackRate,playbackRate,autoplay,loop,controls,volume,muted,defaultMuted'.split(',');
 const _readOnly = 'networkState,readyState,initialTime,startOffsetTime,paused,ended,videoWidth,videoHeight'.split(',');
 
 function _createSetter(attr) {

src/js/tech/html5.js

@@ -1174,6 +1174,21 @@ Html5.resetMediaElement = function(el) {
    */
   'muted',
 
+  /**
+   * Get the value of `defaultMuted` from the media element. `defaultMuted` indicates
+   * that the volume for the media should be set to silent when the video first starts.
+   * This does not actually change the `volume` attribute. After playback has started `muted`
+   * will indicate the current status of the volume and `defaultMuted` will not.
+   *
+   * @method Html5.prototype.defaultMuted
+   * @return {boolean}
+   *         - True if the value of `volume` should be ignored and the audio set to silent.
+   *         - False if the value of `volume` should be used.
+   *
+   * @see [Spec]{@link https://www.w3.org/TR/html5/embedded-content-0.html#dom-media-defaultmuted}
+   */
+  'defaultMuted',
+
   /**
    * Get the value of `poster` from the media element. `poster` indicates
    * that the url of an image file that can/will be shown when no media data is available.
@@ -1309,7 +1324,7 @@ Html5.resetMediaElement = function(el) {
   /**
    * Get the value of `defaultMuted` from the media element. `defaultMuted` indicates
    * whether the media should start muted or not. Only changes the default state of the
-   * media. `muted` and `defaultMuted` can have different values. `muted` indicates the
+   * media. `muted` and `defaultMuted` can have different values. {@link Html5#muted} indicates the
    * current state.
    *
    * @method Html5#defaultMuted
@@ -1337,6 +1352,24 @@ Html5.resetMediaElement = function(el) {
    */
   'playbackRate',
 
+  /**
+   * Get the value of `defaultPlaybackRate` from the media element. `defaultPlaybackRate` indicates
+   * the rate at which the media is currently playing back. This value will not indicate the current
+   * `playbackRate` after playback has started, use {@link Html5#playbackRate} for that.
+   *
+   * Examples:
+   *   - if defaultPlaybackRate is set to 2, media will play twice as fast.
+   *   - if defaultPlaybackRate is set to 0.5, media will play half as fast.
+   *
+   * @method Html5.prototype.defaultPlaybackRate
+   * @return {number}
+   *         The value of `defaultPlaybackRate` from the media element. A number indicating
+   *         the current playback speed of the media, where 1 is normal speed.
+   *
+   * @see [Spec]{@link https://www.w3.org/TR/html5/embedded-content-0.html#dom-media-playbackrate}
+   */
+  'defaultPlaybackRate',
+
   /**
    * Get the value of `played` from the media element. `played` returns a `TimeRange`
    * object representing points in the media timeline that have been played.
@@ -1434,7 +1467,7 @@ Html5.resetMediaElement = function(el) {
   'volume',
 
   /**
-   * Set the value of `muted` on the media element. `muted` indicates the current
+   * Set the value of `muted` on the media element. `muted` indicates that the current
    * audio level should be silent.
    *
    * @method Html5#setMuted
@@ -1446,6 +1479,19 @@ Html5.resetMediaElement = function(el) {
    */
   'muted',
 
+  /**
+   * Set the value of `defaultMuted` on the media element. `defaultMuted` indicates that the current
+   * audio level should be silent, but will only effect the muted level on intial playback..
+   *
+   * @method Html5.prototype.setDefaultMuted
+   * @param {boolean} defaultMuted
+   *        - True if the audio should be set to silent
+   *        - False otherwise
+   *
+   * @see [Spec]{@link https://www.w3.org/TR/html5/embedded-content-0.html#dom-media-defaultmuted}
+   */
+  'defaultMuted',
+
   /**
    * Set the value of `src` on the media element. `src` indicates the current
    * {@link Tech~SourceObject} for the media.
@@ -1532,7 +1578,26 @@ Html5.resetMediaElement = function(el) {
    *
    * @see [Spec]{@link https://www.w3.org/TR/html5/embedded-content-0.html#dom-media-playbackrate}
    */
-  'playbackRate'
+  'playbackRate',
+
+  /**
+   * Set the value of `defaultPlaybackRate` on the media element. `defaultPlaybackRate` indicates
+   * the rate at which the media should play back upon initial startup. Changing this value
+   * after a video has started will do nothing. Instead you should used {@link Html5#setPlaybackRate}.
+   *
+   * Example Values:
+   *   - if playbackRate is set to 2, media will play twice as fast.
+   *   - if playbackRate is set to 0.5, media will play half as fast.
+   *
+   * @method Html5.prototype.setDefaultPlaybackRate
+   * @return {number}
+   *         The value of `defaultPlaybackRate` from the media element. A number indicating
+   *         the current playback speed of the media, where 1 is normal speed.
+   *
+   * @see [Spec]{@link https://www.w3.org/TR/html5/embedded-content-0.html#dom-media-defaultplaybackrate}
+   */
+  'defaultPlaybackRate'
+
 ].forEach(function(prop) {
   Html5.prototype['set' + toTitleCase(prop)] = function(v) {
     this.el_[prop] = v;

test/unit/tech/html5.test.js

@@ -71,17 +71,58 @@ QUnit.test('should detect whether the volume can be changed', function(assert) {
 QUnit.test('test playbackRate', function(assert) {
   // Android 2.3 always returns 0 for playback rate
   if (!Html5.canControlPlaybackRate()) {
-    assert.ok('Playback rate is not supported');
+    assert.ok(true, 'Playback rate is not supported');
     return;
   }
 
   tech.createEl();
 
   tech.el().playbackRate = 1.25;
-  assert.strictEqual(tech.playbackRate(), 1.25);
+  assert.strictEqual(tech.playbackRate(), 1.25, 'can be changed from the element');
 
   tech.setPlaybackRate(0.75);
-  assert.strictEqual(tech.playbackRate(), 0.75);
+  assert.strictEqual(tech.playbackRate(), 0.75, 'can be changed from the API');
+});
+
+QUnit.test('test defaultPlaybackRate', function(assert) {
+  // Android 2.3 always returns 0 for playback rate
+  if (!Html5.canControlPlaybackRate()) {
+    assert.ok(true, 'Playback rate is not supported');
+    return;
+  }
+
+  tech.createEl();
+
+  tech.el().defaultPlaybackRate = 1.25;
+  assert.strictEqual(tech.defaultPlaybackRate(), 1.25, 'can be changed from the element');
+
+  tech.setDefaultPlaybackRate(0.75);
+  assert.strictEqual(tech.defaultPlaybackRate(), 0.75, 'can be changed from the API');
+});
+
+QUnit.test('test volume', function(assert) {
+  if (!Html5.canControlVolume()) {
+    assert.ok(true, 'Volume is not supported');
+    return;
+  }
+
+  tech.createEl();
+
+  tech.el().volume = 0.7;
+  assert.strictEqual(tech.volume(), 0.7, 'can be changed from the element');
+
+  tech.setVolume(0.2);
+  assert.strictEqual(tech.volume(), 0.2, 'can be changed from the API');
+});
+
+QUnit.test('test defaultMuted', function(assert) {
+  tech.createEl();
+
+  tech.el().defaultMuted = true;
+  assert.strictEqual(tech.defaultMuted(), true, 'can be changed from the element');
+
+  tech.setDefaultMuted(false);
+  assert.strictEqual(tech.defaultMuted(), false, 'can be changed from the API');
 });
 
 QUnit.test('should export played', function(assert) {