feat(HLS): Add support for REQ-VIDEO-LAYOUT

demo/config.js

@@ -438,6 +438,19 @@ shakaDemo.Config = class {
     this.addSelectInput_('Preferred HDR Level', 'preferredVideoHdrLevel',
         hdrLevels, hdrLevelNames);
 
+    const videoLayouts = {
+      '': '',
+      'CH-STEREO': 'CH-STEREO',
+      'CH-MONO': 'CH-MONO',
+    };
+    const videoLayoutsNames = {
+      'CH-STEREO': 'Stereoscopic',
+      'CH-MONO': 'Monoscopic',
+      '': 'No Preference',
+    };
+    this.addSelectInput_('Preferred video layout', 'preferredVideoLayout',
+        videoLayouts, videoLayoutsNames);
+
     this.addBoolInput_('Start At Segment Boundary',
         'streaming.startAtSegmentBoundary')
         .addBoolInput_('Ignore Text Stream Failures',

externs/shaka/manifest.js

@@ -364,6 +364,7 @@ shaka.extern.FetchCryptoKeysFunction;
  *   frameRate: (number|undefined),
  *   pixelAspectRatio: (string|undefined),
  *   hdr: (string|undefined),
+ *   videoLayout: (string|undefined),
  *   bandwidth: (number|undefined),
  *   width: (number|undefined),
  *   height: (number|undefined),
@@ -434,6 +435,9 @@ shaka.extern.FetchCryptoKeysFunction;
  * @property {(string|undefined)} hdr
  *   <i>Video streams only.</i> <br>
  *   The Stream's HDR info
+ * @property {(string|undefined)} videoLayout
+ *   <i>Video streams only.</i> <br>
+ *   The Stream's video layout info.
  * @property {(number|undefined)} bandwidth
  *   <i>Audio and video streams only.</i> <br>
  *   The stream's required bandwidth in bits per second.

externs/shaka/offline.js

@@ -122,6 +122,7 @@ shaka.extern.ManifestDB;
  *   frameRate: (number|undefined),
  *   pixelAspectRatio: (string|undefined),
  *   hdr: (string|undefined),
+ *   videoLayout: (string|undefined),
  *   kind: (string|undefined),
  *   language: string,
  *   originalLanguage: (?string|undefined),
@@ -164,6 +165,8 @@ shaka.extern.ManifestDB;
  *   The Stream's pixel aspect ratio
  * @property {(string|undefined)} hdr
  *   The Stream's HDR info
+ * @property {(string|undefined)} videoLayout
+ *   The Stream's video layout info.
  * @property {(string|undefined)} kind
  *   The kind of text stream; undefined for audio/video.
  * @property {string} language

externs/shaka/player.js

@@ -216,6 +216,7 @@ shaka.extern.BufferedInfo;
  *   frameRate: ?number,
  *   pixelAspectRatio: ?string,
  *   hdr: ?string,
+ *   videoLayout: ?string,
  *   mimeType: ?string,
  *   audioMimeType: ?string,
  *   videoMimeType: ?string,
@@ -280,6 +281,8 @@ shaka.extern.BufferedInfo;
  *   The video pixel aspect ratio provided in the manifest, if present.
  * @property {?string} hdr
  *   The video HDR provided in the manifest, if present.
+ * @property {?string} videoLayout
+ *   The video layout provided in the manifest, if present.
  * @property {?string} mimeType
  *   The MIME type of the content provided in the manifest.
  * @property {?string} audioMimeType
@@ -1537,6 +1540,7 @@ shaka.extern.OfflineConfiguration;
  *   preferredAudioCodecs: !Array.<string>,
  *   preferredAudioChannelCount: number,
  *   preferredVideoHdrLevel: string,
+ *   preferredVideoLayout: string,
  *   preferredDecodingAttributes: !Array.<string>,
  *   preferForcedSubs: boolean,
  *   restrictions: shaka.extern.Restrictions,
@@ -1597,6 +1601,12 @@ shaka.extern.OfflineConfiguration;
  *   Defaults to 'AUTO'.
  *   Note that one some platforms, such as Chrome, attempting to play PQ content
  *   may cause problems.
+ * @property {string} preferredVideoLayout
+ *   The preferred video layout of the video.
+ *   Can be 'CH-STEREO', 'CH-MONO', or '' for no preference.
+ *   If the content is predominantly stereoscopic you should use 'CH-STEREO'.
+ *   If the content is predominantly monoscopic you should use 'CH-MONO'.
+ *   Defaults to ''.
  * @property {!Array.<string>} preferredDecodingAttributes
  *   The list of preferred attributes of decodingInfo, in the order of their
  *   priorities.

lib/dash/dash_parser.js

@@ -1470,6 +1470,7 @@ shaka.dash.DashParser = class {
         spatialAudio,
         closedCaptions,
         hdr,
+        videoLayout: undefined,
         tilesLayout,
         matchedStreams: [],
         accessibilityPurpose,

lib/hls/hls_parser.js

@@ -720,7 +720,8 @@ shaka.hls.HlsParser = class {
 
       if (type == 'video') {
         this.addVideoAttributes_(streamInfo.stream, width, height,
-            /* frameRate= */ null, /* videoRange= */ null);
+            /* frameRate= */ null, /* videoRange= */ null,
+            /* videoLayout= */ null);
       }
 
       // Wrap the stream from that stream info with a variant.
@@ -1220,6 +1221,21 @@ shaka.hls.HlsParser = class {
 
       const videoRange = tag.getAttributeValue('VIDEO-RANGE');
 
+      let videoLayout = tag.getAttributeValue('REQ-VIDEO-LAYOUT');
+      if (videoLayout && videoLayout.includes(',')) {
+        // If multiple video layout strings are present, pick the first valid
+        // one.
+        const layoutStrings = videoLayout.split(',').filter((layoutString) => {
+          return layoutString == 'CH-STEREO' || layoutString == 'CH-MONO';
+        });
+        videoLayout = layoutStrings[0];
+      }
+      // According to the HLS spec:
+      // By default a video variant is monoscopic, so an attribute
+      // consisting entirely of REQ-VIDEO-LAYOUT="CH-MONO" is unnecessary
+      // and SHOULD NOT be present.
+      videoLayout = videoLayout || 'CH-MONO';
+
       const streamInfos = this.createStreamInfosForVariantTag_(tag,
           resolution, frameRate);
 
@@ -1234,6 +1250,7 @@ shaka.hls.HlsParser = class {
           height,
           frameRate,
           videoRange,
+          videoLayout,
           drmInfos,
           keyIds);
     });
@@ -1510,20 +1527,21 @@ shaka.hls.HlsParser = class {
    * @param {?string} height
    * @param {?string} frameRate
    * @param {?string} videoRange
+   * @param {?string} videoLayout
    * @param {!Array.<shaka.extern.DrmInfo>} drmInfos
    * @param {!Set.<string>} keyIds
    * @return {!Array.<!shaka.extern.Variant>}
    * @private
    */
   createVariants_(
       audioInfos, videoInfos, bandwidth, width, height, frameRate, videoRange,
-      drmInfos, keyIds) {
+      videoLayout, drmInfos, keyIds) {
     const ContentType = shaka.util.ManifestParserUtils.ContentType;
     const DrmEngine = shaka.media.DrmEngine;
 
     for (const info of videoInfos) {
       this.addVideoAttributes_(
-          info.stream, width, height, frameRate, videoRange);
+          info.stream, width, height, frameRate, videoRange, videoLayout);
     }
 
     // In case of audio-only or video-only content or the audio/video is
@@ -2376,6 +2394,7 @@ shaka.hls.HlsParser = class {
       spatialAudio,
       closedCaptions,
       hdr: undefined,
+      videoLayout: undefined,
       tilesLayout: undefined,
       accessibilityPurpose: null,
       external: false,
@@ -3464,14 +3483,17 @@ shaka.hls.HlsParser = class {
    * @param {?string} height
    * @param {?string} frameRate
    * @param {?string} videoRange
+   * @param {?string} videoLayout
    * @private
    */
-  addVideoAttributes_(stream, width, height, frameRate, videoRange) {
+  addVideoAttributes_(stream, width, height, frameRate, videoRange,
+      videoLayout) {
     if (stream) {
       stream.width = Number(width) || undefined;
       stream.height = Number(height) || undefined;
       stream.frameRate = Number(frameRate) || undefined;
       stream.hdr = videoRange || undefined;
+      stream.videoLayout = videoLayout || undefined;
     }
   }
 

lib/media/adaptation_set_criteria.js

@@ -61,13 +61,14 @@ shaka.media.ExampleBasedCriteria = class {
     const role = '';
     const label = '';
     const hdrLevel = '';
+    const videoLayout = '';
     const channelCount = example.audio && example.audio.channelsCount ?
                          example.audio.channelsCount :
                          0;
 
     /** @private {!shaka.media.AdaptationSetCriteria} */
     this.fallback_ = new shaka.media.PreferenceBasedCriteria(
-        example.language, role, channelCount, hdrLevel, label,
+        example.language, role, channelCount, hdrLevel, videoLayout, label,
         codecSwitchingStrategy, enableAudioGroups);
   }
 
@@ -106,11 +107,12 @@ shaka.media.PreferenceBasedCriteria = class {
    * @param {string} role
    * @param {number} channelCount
    * @param {string} hdrLevel
+   * @param {string} videoLayout
    * @param {string=} label
    * @param {shaka.config.CodecSwitchingStrategy=} codecSwitchingStrategy
    * @param {boolean=} enableAudioGroups
    */
-  constructor(language, role, channelCount, hdrLevel, label = '',
+  constructor(language, role, channelCount, hdrLevel, videoLayout, label = '',
       codecSwitchingStrategy = shaka.config.CodecSwitchingStrategy.RELOAD,
       enableAudioGroups = false) {
     /** @private {string} */
@@ -122,6 +124,8 @@ shaka.media.PreferenceBasedCriteria = class {
     /** @private {string} */
     this.hdrLevel_ = hdrLevel;
     /** @private {string} */
+    this.videoLayout_ = videoLayout;
+    /** @private {string} */
     this.label_ = label;
     /** @private {shaka.config.CodecSwitchingStrategy} */
     this.codecSwitchingStrategy_ = codecSwitchingStrategy;
@@ -156,6 +160,17 @@ shaka.media.PreferenceBasedCriteria = class {
       shaka.log.warning('No exact match for variant role could be found.');
     }
 
+    if (this.videoLayout_) {
+      const byVideoLayout = Class.filterVariantsByVideoLayout_(
+          current, this.videoLayout_);
+      if (byVideoLayout.length) {
+        current = byVideoLayout;
+      } else {
+        shaka.log.warning(
+            'No exact match for the video layout could be found.');
+      }
+    }
+
     if (this.hdrLevel_) {
       const byHdrLevel = Class.filterVariantsByHDRLevel_(
           current, this.hdrLevel_);
@@ -289,4 +304,22 @@ shaka.media.PreferenceBasedCriteria = class {
       return true;
     });
   }
+
+
+  /**
+   * Filters variants according to the given video layout config.
+   *
+   * @param {!Array.<shaka.extern.Variant>} variants
+   * @param {string} videoLayout
+   * @private
+   */
+  static filterVariantsByVideoLayout_(variants, videoLayout) {
+    return variants.filter((variant) => {
+      if (variant.video && variant.video.videoLayout &&
+          variant.video.videoLayout != videoLayout) {
+        return false;
+      }
+      return true;
+    });
+  }
 };

lib/mss/mss_parser.js

@@ -537,6 +537,7 @@ shaka.mss.MssParser = class {
       spatialAudio: false,
       closedCaptions: null,
       hdr: undefined,
+      videoLayout: undefined,
       tilesLayout: undefined,
       matchedStreams: [],
       mssPrivateData: {

lib/offline/indexeddb/v1_storage_cell.js

@@ -158,6 +158,7 @@ shaka.offline.indexeddb.V1StorageCell = class
       frameRate: old.frameRate,
       pixelAspectRatio: undefined,
       hdr: undefined,
+      videoLayout: undefined,
       kind: old.kind,
       language: old.language,
       originalLanguage: old.language || null,

lib/offline/indexeddb/v2_storage_cell.js

@@ -107,6 +107,7 @@ shaka.offline.indexeddb.V2StorageCell = class
       frameRate: old.frameRate,
       pixelAspectRatio: old.pixelAspectRatio,
       hdr: undefined,
+      videoLayout: undefined,
       kind: old.kind,
       language: old.language,
       originalLanguage: old.language || null,

lib/offline/manifest_converter.js

@@ -190,6 +190,7 @@ shaka.offline.ManifestConverter = class {
       frameRate: streamDB.frameRate,
       pixelAspectRatio: streamDB.pixelAspectRatio,
       hdr: streamDB.hdr,
+      videoLayout: streamDB.videoLayout,
       kind: streamDB.kind,
       encrypted: streamDB.encrypted,
       drmInfos: [],

lib/offline/storage.js

@@ -1309,6 +1309,7 @@ shaka.offline.Storage = class {
       frameRate: stream.frameRate,
       pixelAspectRatio: stream.pixelAspectRatio,
       hdr: stream.hdr,
+      videoLayout: stream.videoLayout,
       kind: stream.kind,
       language: stream.language,
       originalLanguage: stream.originalLanguage,

lib/player.js

@@ -619,6 +619,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
             this.config_.preferredVariantRole,
             this.config_.preferredAudioChannelCount,
             this.config_.preferredVideoHdrLevel,
+            this.config_.preferredVideoLayout,
             this.config_.preferredAudioLabel,
             this.config_.mediaSource.codecSwitchingStrategy,
             this.config_.manifest.dash.enableAudioGroups);
@@ -2152,6 +2153,7 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
             this.config_.preferredVariantRole,
             this.config_.preferredAudioChannelCount,
             this.config_.preferredVideoHdrLevel,
+            this.config_.preferredVideoLayout,
             this.config_.preferredAudioLabel,
             this.config_.mediaSource.codecSwitchingStrategy,
             this.config_.manifest.dash.enableAudioGroups);
@@ -4311,8 +4313,13 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
   selectAudioLanguage(language, role, channelsCount = 0, safeMargin = 0) {
     if (this.manifest_ && this.playhead_) {
       this.currentAdaptationSetCriteria_ =
-          new shaka.media.PreferenceBasedCriteria(language, role || '',
-              channelsCount, /* hdrLevel= */ '', /* label= */ '',
+          new shaka.media.PreferenceBasedCriteria(
+              language,
+              role || '',
+              channelsCount,
+              /* hdrLevel= */ '',
+              /* videoLayout= */ '',
+              /* label= */ '',
               this.config_.mediaSource.codecSwitchingStrategy,
               this.config_.manifest.dash.enableAudioGroups);
 
@@ -4431,7 +4438,12 @@ shaka.Player = class extends shaka.util.FakeEventTarget {
       // label have the same language.
       this.currentAdaptationSetCriteria_ =
           new shaka.media.PreferenceBasedCriteria(
-              firstVariantWithLabel.language, '', 0, '', label,
+              firstVariantWithLabel.language,
+              /* role= */ '',
+              /* channelCount= */ 0,
+              /* hdrLevel= */ '',
+              /* videoLayout= */ '',
+              label,
               this.config_.mediaSource.codecSwitchingStrategy,
               this.config_.manifest.dash.enableAudioGroups);
 

lib/util/player_configuration.js

@@ -345,6 +345,7 @@ shaka.util.PlayerConfiguration = class {
       preferredTextRole: '',
       preferredAudioChannelCount: 2,
       preferredVideoHdrLevel: 'AUTO',
+      preferredVideoLayout: '',
       preferredVideoCodecs: [],
       preferredAudioCodecs: [],
       preferForcedSubs: false,