fix: Add optional content workaround to force ENCA.ChannelCount to 2 for EAC-3 Audio init segments (#8517)

In short, we've discovered a packaging issue on some of our streams
where the ChannelCount field of the enca box contains an invalid value
of 7. According to the dolby spec (and confirmed by their validator):
- This field should always be 2
- This field should be ignored by the decoder/user agent

From talking to the Dolby folks, it seems that some devices erroneously
do not ignore this value. Chromecast is one of said devices. Playing
back an EAC-3 audio track on Chromecast packaged this way causes an
immediate fatal decoding failure. -- rewriting that box content client
side to force a value of 2 fixes playback without any other issues.

This fix will take the init segment (if it's audio and the workaround is
enabled), and replace the ChannelCount with 2 if and only if the
original audio codec was EC3.

Given that these streams were packaged by Bento4, I figure it may be
possible for this to happen for others. The workaround is generic enough
that I think it's reasonable to have as an optional content workaround
in Shaka.

Here's some output from the Dolby validator indicating the requirement
here:
```
ERROR: For an [EC3] stream, in MP4 EC3SampleEntryBox, the "ChannelCount" must set to 2.  (ETSI TS 102 366 V1.4.1 (2017-09) F.5.1)
```

---------

Co-authored-by: Nicholas Crast <[email protected]>
Co-authored-by: Álvaro Velad Galván <[email protected]>

Author: 3 people

demo/config.js

@@ -694,6 +694,8 @@ shakaDemo.Config = class {
         .addBoolInput_('Force Transmux', 'mediaSource.forceTransmux')
         .addBoolInput_('Insert fake encryption in init segments when needed ' +
             'by the platform.', 'mediaSource.insertFakeEncryptionInInit')
+        .addBoolInput_('Force enca.ChannelCount to 2 for EC-3 audio if ' +
+          'needed by the platform.', 'mediaSource.correctEc3Enca')
         .addSelectInput_(
             'Codec Switching Strategy',
             'mediaSource.codecSwitchingStrategy',

externs/shaka/player.js

@@ -2183,6 +2183,7 @@ shaka.extern.NetworkingConfiguration;
  *   addExtraFeaturesToSourceBuffer: function(string): string,
  *   forceTransmux: boolean,
  *   insertFakeEncryptionInInit: boolean,
+ *   correctEc3Enca: boolean,
  *   modifyCueCallback: shaka.extern.TextParser.ModifyCueCallback,
  *   dispatchAllEmsgBoxes: boolean,
  *   useSourceElements: boolean,
@@ -2221,6 +2222,13 @@ shaka.extern.NetworkingConfiguration;
  *   <br><br>
  *   <br>
  *   Defaults to <code>true</code>.
+ * @property {boolean} correctEc3Enca
+ *   If true, will apply a work-around for Audio init segments signaling
+ *   EC-3 codec with protection. This will force the ChannelCount field
+ *   of the 'enca' box to be set to 2, which is required via the dolby
+ *   spec.
+ *   <br>
+ *   This value defaults to <code>false</code>.
  * @property {shaka.extern.TextParser.ModifyCueCallback} modifyCueCallback
  *    A callback called for each cue after it is parsed, but right before it
  *    is appended to the presentation.

lib/media/content_workarounds.js

@@ -22,6 +22,62 @@ goog.require('shaka.util.Uint8ArrayUtils');
  * A collection of methods to work around content issues on various platforms.
  */
 shaka.media.ContentWorkarounds = class {
+  /**
+   * For EAC-3 audio, the "enca" box ChannelCount field
+   * MUST always be set to 2.
+   * See ETSI TS 102 366 V1.2.1 Sec F.3
+   *
+   * Clients SHOULD ignore this value; however, it has been discovered that
+   * some user agents don't, and instead, invalid values here can cause decoder
+   * failures to be thrown (this has been observed with Chromecast).
+   *
+   * Given that this value MUST be hard-coded to 2, and that clients "SHALL"
+   * ignore the value, it seems safe to manipulate the value to be 2 even when
+   * the packager has provided a different value.
+   * @param {!BufferSource} initSegmentBuffer
+   * @return {!Uint8Array}
+   */
+  static correctEnca(initSegmentBuffer) {
+    const initSegment = shaka.util.BufferUtils.toUint8(initSegmentBuffer);
+    const modifiedInitSegment = initSegment;
+
+    /**
+     * Skip reserved bytes: 6
+     * Skip data_reference_index: 2
+     * Skip reserved bytes: 8
+     */
+    const encaChannelCountOffset = 16;
+
+    /** @type {?DataView} */
+    let encaBoxDataView = null;
+
+    new shaka.util.Mp4Parser()
+        .box('moov', shaka.util.Mp4Parser.children)
+        .box('trak', shaka.util.Mp4Parser.children)
+        .box('mdia', shaka.util.Mp4Parser.children)
+        .box('minf', shaka.util.Mp4Parser.children)
+        .box('stbl', shaka.util.Mp4Parser.children)
+        .fullBox('stsd', shaka.util.Mp4Parser.sampleDescription)
+        .box('enca', (box) => {
+          encaBoxDataView = box.reader.getDataView();
+          return shaka.util.Mp4Parser.audioSampleEntry(box);
+        })
+        .box('sinf', shaka.util.Mp4Parser.children)
+        .box('frma', (box) => {
+          box.parser.stop();
+          const {codec} = shaka.util.Mp4BoxParsers.parseFRMA(box.reader);
+          if (codec === 'ec-3' &&
+                encaBoxDataView &&
+                encaBoxDataView.getUint16(encaChannelCountOffset) !== 2
+          ) {
+            encaBoxDataView.setUint16(encaChannelCountOffset, 2);
+          }
+        })
+        .parse(initSegment);
+
+    return modifiedInitSegment;
+  }
+
   /**
    * Transform the init segment into a new init segment buffer that indicates
    * encryption.  If the init segment already indicates encryption, return the

lib/media/media_source_engine.js

@@ -2165,6 +2165,7 @@ shaka.media.MediaSourceEngine = class {
    * @private
    */
   workAroundBrokenPlatforms_(stream, segment, reference, contentType) {
+    const ContentType = shaka.util.ManifestParserUtils.ContentType;
     const Platform = shaka.util.Platform;
 
     const isMp4 = shaka.util.MimeUtils.getContainerType(
@@ -2182,6 +2183,12 @@ shaka.media.MediaSourceEngine = class {
     }
     const uri = reference ? reference.getUris()[0] : null;
 
+    if (this.config_.correctEc3Enca &&
+      isInitSegment &&
+      contentType === ContentType.AUDIO) {
+      segment = shaka.media.ContentWorkarounds.correctEnca(segment);
+    }
+
     // If:
     //   1. the configuration tells to insert fake encryption,
     //   2. and this is an init segment or media segment,

lib/util/player_configuration.js

@@ -433,6 +433,7 @@ shaka.util.PlayerConfiguration = class {
       },
       forceTransmux: false,
       insertFakeEncryptionInInit: true,
+      correctEc3Enca: false,
       modifyCueCallback: (cue, uri) => {
         return shaka.util.ConfigUtils.referenceParametersAndReturn(
             [cue, uri],

test/media/content_workarounds_unit.js

@@ -257,6 +257,41 @@ describe('ContentWorkarounds', () => {
           .parse(faked);
       expect(spy).toHaveBeenCalled();
     });
+
+    describe('enca correction', () => {
+      const initSegmentUri = '/base/test/test/assets/incorrect-enca-init.mp4';
+      /** @type {!ArrayBuffer} */
+      let initSegmentData;
+
+      const getChannelCount = (initSegment) => {
+        let channelCount = 0;
+        new shaka.util.Mp4Parser()
+            .box('moov', shaka.util.Mp4Parser.children)
+            .box('trak', shaka.util.Mp4Parser.children)
+            .box('mdia', shaka.util.Mp4Parser.children)
+            .box('minf', shaka.util.Mp4Parser.children)
+            .box('stbl', shaka.util.Mp4Parser.children)
+            .fullBox('stsd', shaka.util.Mp4Parser.sampleDescription)
+            .box('enca', (box) => {
+              const data = shaka.util.Mp4BoxParsers
+                  .audioSampleEntry(box.reader);
+              channelCount = data.channelCount;
+            }).parse(initSegment);
+        return channelCount;
+      };
+
+      beforeEach(async () => {
+        initSegmentData = await shaka.test.Util.fetch(initSegmentUri);
+      });
+
+      it('should replace the ChannelCount in the enca box', () => {
+        const ContentWorkarounds = shaka.media.ContentWorkarounds;
+        expect(getChannelCount(initSegmentData)).toBe(7);
+
+        const modified = ContentWorkarounds.correctEnca(initSegmentData);
+        expect(getChannelCount(modified)).toBe(2);
+      });
+    });
   });
 
   /**