feat: Add audioPosterMode option (#7629)

Author: harisha-swaminathan

docs/guides/options.md

@@ -21,6 +21,7 @@
   * [width](#width)
 * [Video.js-specific Options](#videojs-specific-options)
   * [aspectRatio](#aspectratio)
+  * [audioPosterMode](#audiopostermode)
   * [autoSetup](#autosetup)
   * [breakpoints](#breakpoints)
   * [children](#children)
@@ -181,6 +182,13 @@ Puts the player in [fluid](#fluid) mode and the value is used when calculating t
 
 Alternatively, the classes `vjs-16-9`, `vjs-9-16`, `vjs-4-3` or `vjs-1-1` can be added to the player.
 
+### `audioPosterMode`
+
+> Type: `boolean`
+> Default: `false`
+
+If set to true, it enables the poster viewer experience by hiding the video element and displaying the poster image persistently. This option can be set to `true` or `false` by calling `audioPosterMode([true|false])` at runtime.
+
 ### `autoSetup`
 
 > Type: `boolean`

src/css/components/_poster.scss

@@ -16,17 +16,14 @@
   height: 100%;
 }
 
-// Hide the poster after the video has started playing
-.vjs-has-started .vjs-poster {
+// Hide the poster after the video has started playing and when native controls are used
+.vjs-has-started .vjs-poster,
+.vjs-using-native-controls .vjs-poster {
   display: none;
 }
 
-// Don't hide the poster if we're playing audio
-.vjs-audio.vjs-has-started .vjs-poster {
+// Don't hide the poster if we're playing audio or when audio-poster-mode is true
+.vjs-audio.vjs-has-started .vjs-poster, 
+.vjs-has-started.vjs-audio-poster-mode  .vjs-poster {
   display: block;
 }
-
-// Hide the poster when native controls are used otherwise it covers them
-.vjs-using-native-controls .vjs-poster {
-  display: none;
-}

src/js/player.js

@@ -4293,6 +4293,37 @@ class Player extends Component {
     return !!this.isAudio_;
   }
 
+  /**
+   * Get the current audioPosterMode state or set audioPosterMode to true or false
+   *
+   * @param {boolean} [value]
+   *         The value to set audioPosterMode to.
+   *
+   * @return {boolean}
+   *         True if audioPosterMode is on, false otherwise.
+   */
+  audioPosterMode(value) {
+
+    if (this.audioPosterMode_ === undefined) {
+      this.audioPosterMode_ = this.options_.audioPosterMode;
+    }
+
+    if (typeof value !== 'boolean' || value === this.audioPosterMode_) {
+      return this.audioPosterMode_;
+    }
+
+    this.audioPosterMode_ = value;
+
+    if (this.audioPosterMode_) {
+      this.tech_.hide();
+      this.addClass('vjs-audio-poster-mode');
+      return;
+    }
+    // Show the video element and hide the poster image if audioPosterMode is set to false
+    this.tech_.show();
+    this.removeClass('vjs-audio-poster-mode');
+  }
+
   /**
    * A helper method for adding a {@link TextTrack} to our
    * {@link TextTrackList}.
@@ -5099,7 +5130,8 @@ Player.prototype.options_ = {
   },
 
   breakpoints: {},
-  responsive: false
+  responsive: false,
+  audioPosterMode: false
 };
 
 [

test/unit/player.test.js

@@ -1570,6 +1570,39 @@ QUnit.test('should add an audio player region if an audio el is used', function(
   player.dispose();
 });
 
+QUnit.test('default audioPosterMode value at player creation', function(assert) {
+  const player = TestHelpers.makePlayer({});
+
+  assert.ok(player.audioPosterMode() === false, 'audioPosterMode is false by default');
+
+  const player2 = TestHelpers.makePlayer({
+    audioPosterMode: true
+  });
+
+  assert.ok(player2.audioPosterMode() === true, 'audioPosterMode can be set to true when the player is created');
+  player.dispose();
+  player2.dispose();
+});
+
+QUnit.test('get and set audioPosterMode value', function(assert) {
+  const player = TestHelpers.makePlayer({});
+
+  player.audioPosterMode(true);
+  assert.ok(player.audioPosterMode() === true, 'audioPosterMode is set to true');
+});
+
+QUnit.test('vjs-audio-poster-mode class and video element visibility when audioPosterMode is true', function(assert) {
+  const player = TestHelpers.makePlayer({});
+
+  player.audioPosterMode(true);
+  assert.ok(player.el().className.indexOf('vjs-audio-poster-mode') !== -1, 'vjs-audio-poster-mode class is present');
+  assert.ok(player.tech_.el().className.indexOf('vjs-hidden') !== -1, 'video element is hidden');
+
+  player.audioPosterMode(false);
+  assert.ok(player.el().className.indexOf('vjs-audio-poster-mode') === -1, 'vjs-audio-poster-mode class is removed');
+  assert.ok(player.tech_.el().className.indexOf('vjs-hidden') === -1, 'video element is visible');
+});
+
 QUnit.test('should setScrubbing when seeking or not seeking', function(assert) {
   const player = TestHelpers.makePlayer();
   let isScrubbing;