[Proposal] scte214 - use supplemental codec instead of base codec if it's supported

src/manifest/representation.ts

@@ -111,6 +111,20 @@ class Representation {
    */
   public codec : string | undefined;
 
+  /**
+   * Supplemental codecs are defined as backwards-compatible codecs enhancing
+   * the experience of a base layer codec
+   * Optional attribute, a representation may not have supplemental codecs
+   */
+  public supplementalCodec?: string | undefined;
+
+  /**
+   * `true` if the Supplemental codec is in a supported codec
+   * `false` if there is no supplemental codec or
+   * if the supplemental codec is not supported
+   */
+  public isSupplementalCodecSupported: boolean;
+
   /**
    * A string describing the mime-type for this Representation.
    * Examples: audio/mp4, video/webm, application/mp4, text/plain
@@ -191,8 +205,26 @@ class Representation {
 
     this.cdnMetadata = args.cdnMetadata;
 
+    if (args.supplementalCodecs !== undefined) {
+      this.supplementalCodec = args.supplementalCodecs;
+    }
+
+    if (this.supplementalCodec !== undefined) {
+      const supplementalCodecMimeTypeStr =
+       `${this.mimeType ?? ""};codecs="${this.supplementalCodec ?? ""}"`;
+      const isSupplementalCodecSupported = isCodecSupported(supplementalCodecMimeTypeStr);
+      this.isSupplementalCodecSupported = isSupplementalCodecSupported;
+    } else {
+      this.isSupplementalCodecSupported = false;
+    }
+
     this.index = args.index;
-    if (opts.type === "audio" || opts.type === "video") {
+
+    if (this.isSupplementalCodecSupported) {
+    // The supplemental codec being supported indicate that the base codec will also
+    // be supported as the supplemental codec is backwards compatible with base codec
+      this.isSupported = true;
+    } else if (opts.type === "audio" || opts.type === "video") {
       const mimeTypeStr = this.getMimeTypeString();
       const isSupported = isCodecSupported(mimeTypeStr);
       if (!isSupported) {
@@ -210,7 +242,11 @@ class Representation {
    * @returns {string}
    */
   public getMimeTypeString() : string {
-    return `${this.mimeType ?? ""};codecs="${this.codec ?? ""}"`;
+    if (this.isSupplementalCodecSupported) {
+      return `${this.mimeType ?? ""};codecs="${this.supplementalCodec ?? ""}"`;
+    } else {
+      return `${this.mimeType ?? ""};codecs="${this.codec ?? ""}"`;
+    }
   }
 
   /**
@@ -387,17 +423,38 @@ class Representation {
    * @returns {Object}
    */
   public toAudioRepresentation(): IAudioRepresentation {
-    const { id, isSpatialAudio, bitrate, codec } = this;
-    return { id, isSpatialAudio, bitrate, codec };
+    const { id,
+            isSpatialAudio,
+            bitrate,
+            codec,
+            supplementalCodec,
+            isSupplementalCodecSupported,
+    } = this;
+    // Depending if the device can play the supplemental codec or not
+    // We return as codec the codec that WILL be played if this representation is chosen
+    const codecInUse = isSupplementalCodecSupported ? supplementalCodec : codec;
+    return { id, isSpatialAudio, bitrate, codec: codecInUse };
   }
 
   /**
    * Format Representation as an `IVideoRepresentation`.
    * @returns {Object}
    */
   public toVideoRepresentation(): IVideoRepresentation {
-    const { id, bitrate, frameRate, width, height, codec, hdrInfo } = this;
-    return { id, bitrate, frameRate, width, height, codec, hdrInfo };
+    const { id,
+            bitrate,
+            frameRate,
+            width,
+            height,
+            codec,
+            hdrInfo,
+            supplementalCodec,
+            isSupplementalCodecSupported,
+    } = this;
+    // Depending if the device can play the supplemental codec or not
+    // We return as codec the codec that WILL be played if this representation is chosen
+    const codecInUse = isSupplementalCodecSupported ? supplementalCodec : codec;
+    return { id, bitrate, frameRate, width, height, codec: codecInUse, hdrInfo };
   }
 }
 

src/parsers/manifest/dash/common/parse_representations.ts

@@ -213,6 +213,17 @@ export default function parseRepresentations(
       codecs = codecs === "mp4a.40.02" ? "mp4a.40.2" : codecs;
       parsedRepresentation.codecs = codecs;
     }
+
+    let supplementalCodecs: string | undefined;
+    if (representation.attributes.supplementalCodecs != null) {
+      supplementalCodecs = representation.attributes.supplementalCodecs;
+    } else if (adaptation.attributes.supplementalCodecs != null) {
+      supplementalCodecs = adaptation.attributes.supplementalCodecs;
+    }
+    if (supplementalCodecs != null) {
+      parsedRepresentation.supplementalCodecs = supplementalCodecs;
+    }
+
     if (representation.attributes.frameRate != null) {
       parsedRepresentation.frameRate =
         representation.attributes.frameRate;

src/parsers/manifest/dash/js-parser/node_parsers/AdaptationSet.ts

@@ -34,6 +34,7 @@ import {
   parseMPDFloat,
   parseMPDInteger,
   parseScheme,
+  parseSupplementalCodec,
   ValueParser,
 } from "./utils";
 
@@ -296,6 +297,12 @@ function parseAdaptationSetAttributes(
         parsedAdaptation.codecs = attribute.value;
         break;
 
+      case "scte214:supplementalCodecs":
+        parseValue(attribute.value,  { asKey: "supplementalCodecs",
+                                       parser: parseSupplementalCodec,
+                                       dashName: "scte214:supplementalCodecs" });
+        break;
+
       case "codingDependency":
         parseValue(attribute.value, { asKey: "codingDependency",
                                       parser: parseBoolean,

src/parsers/manifest/dash/js-parser/node_parsers/Representation.ts

@@ -30,6 +30,7 @@ import {
   parseMPDFloat,
   parseMPDInteger,
   parseScheme,
+  parseSupplementalCodec,
   ValueParser,
 } from "./utils";
 
@@ -184,6 +185,12 @@ function parseRepresentationAttributes(
                                  dashName: "qualityRanking" });
         break;
 
+      case "scte214:supplementalCodecs":
+        parseValue(attr.value,  { asKey: "supplementalCodecs",
+                                  parser: parseSupplementalCodec,
+                                  dashName: "scte214:supplementalCodecs" });
+        break;
+
       case "segmentProfiles":
         attributes.segmentProfiles = attr.value;
         break;

src/parsers/manifest/dash/js-parser/node_parsers/__tests__/utils.test.ts

@@ -17,6 +17,7 @@
 import {
   MPDError,
   parseBoolean,
+  parseSupplementalCodec,
   parseByteRange,
   parseDateTime,
   parseDuration,
@@ -79,6 +80,35 @@ describe("dash parser helpers", function() {
     });
   });
 
+  describe("parseSupplementalCodec", () => {
+    it("should return the codec unchanged if there is only one codec", () => {
+      expect(parseSupplementalCodec("avc1.4d400d")).toEqual(["avc1.4d400d", null]);
+    });
+    it("should trim starting and ending whitespace",  () => {
+      expect(
+        parseSupplementalCodec("  avc1.4d400d  "))
+        .toEqual(["avc1.4d400d", null]);
+    });
+    it("should return comma-separated list if input is whitespace-separated" , () => {
+      expect(
+        parseSupplementalCodec("avc1.4d400d avc1.4d4015"))
+        .toEqual(["avc1.4d400d, avc1.4d4015", null]);
+    });
+    it("should return comma-separated value if input is alreadu comma-separated" , () => {
+      expect(
+        parseSupplementalCodec("avc1.4d400d, avc1.4d4015"))
+        .toEqual(["avc1.4d400d, avc1.4d4015", null]);
+    });
+
+    it(`should return comma-separated value if input is mix of comma and 
+    whitespace separated list`
+    , () => {
+      expect(
+        parseSupplementalCodec("avc1.4d400d avc1.4d4015, avc1.4d401f"))
+        .toEqual(["avc1.4d400d, avc1.4d4015, avc1.4d401f", null]);
+    });
+  });
+
   describe("parseDateTime", () => {
     it("should correctly parse a given date into a timestamp", () => {
       expect(parseDateTime("1970-01-01T00:00:00Z", "a")).toEqual([0, null]);

src/parsers/manifest/dash/js-parser/node_parsers/utils.ts

@@ -28,6 +28,41 @@ const iso8601Duration =
   /^P(([\d.]*)Y)?(([\d.]*)M)?(([\d.]*)D)?T?(([\d.]*)H)?(([\d.]*)M)?(([\d.]*)S)?/;
 const rangeRe = /([0-9]+)-([0-9]+)/;
 
+
+const supplementalCodecSeparator = /([,]? +)/g;
+/**
+ * Parse SCTE 214 supplemental codec string into RFC4281 codec string
+ *
+ * The returned value is a tuple of two elements where:
+ *   1. the first value is the parsed value - or `undefined` if the value is empty
+ *   2. the second value is a possible error encountered while parsing this
+ *      value - set to `null` if no error was encountered.
+ *
+ * SCTE 214 defines supplemental codecs as a whitespace-separated multiple list of
+ * codec strings
+ *
+ * RFC4281 defines codecs as a comma-separated list of codec strings.
+ *
+ * This two syntax differs and this parser is used to convert SCTE214
+ * to be compliant with what MSE APIs expect
+ *
+ * @param {string} val - The codec string to parse
+ * @returns { Array.<string | undefined | null>}
+ */
+function parseSupplementalCodec(
+  val: string
+) : [string ,
+      MPDError | null] {
+
+  if (isNonEmptyString(val)) {
+    const parsedValue = val
+      .trim()
+      .replace(supplementalCodecSeparator, ", ");
+    return [parsedValue, null];
+  }
+  return ["", null];
+}
+
 /**
  * Parse MPD boolean attributes.
  *
@@ -373,6 +408,7 @@ export {
   MPDError,
   ValueParser,
   parseBase64,
+  parseSupplementalCodec,
   parseBoolean,
   parseByteRange,
   parseDateTime,

src/parsers/manifest/dash/node_parser_types.ts

@@ -232,6 +232,7 @@ export interface IAdaptationSetAttributes {
   segmentAlignment? : number|boolean;
   segmentProfiles? : string;
   subsegmentAlignment? : number|boolean;
+  supplementalCodecs?: string;
   width? : number;
   availabilityTimeComplete?: boolean;
   availabilityTimeOffset?: number;
@@ -271,6 +272,7 @@ export interface IRepresentationAttributes {
   profiles? : string;
   qualityRanking? : number;
   segmentProfiles? : string;
+  supplementalCodecs?: string;
   width? : number;
   availabilityTimeComplete?: boolean;
   availabilityTimeOffset?: number;

src/parsers/manifest/types.ts

@@ -160,6 +160,8 @@ export interface IParsedRepresentation {
   hdrInfo?: IHDRInformation | undefined;
   /** `true` if audio has Dolby Atmos. */
   isSpatialAudio?: boolean | undefined;
+
+  supplementalCodecs? : string | undefined;
 }
 
 /** Every possible types an Adaptation can have. */