Source: lib/cea/cea_decoder.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.cea.CeaDecoder');
  9. goog.require('shaka.cea.Cea608DataChannel');
  10. goog.require('shaka.cea.Cea708Service');
  11. goog.require('shaka.cea.DtvccPacketBuilder');
  12. goog.require('shaka.log');
  13. goog.require('shaka.media.ClosedCaptionParser');
  14. goog.require('shaka.util.DataViewReader');
  15. goog.require('shaka.util.Error');
  16. goog.requireType('shaka.cea.DtvccPacket');
  19. /**
  20.  * CEA-X08 captions decoder.
  21.  * @implements {shaka.extern.ICaptionDecoder}
  22.  * @export
  23.  */
  24. shaka.cea.CeaDecoder = class {
  25.   /** */
  26.   constructor() {
  27.     /**
  28.      * An array of CEA-608 closed caption data extracted for decoding.
  29.      * @private {!Array<!shaka.cea.Cea608DataChannel.Cea608Packet>}
  30.      */
  31.     this.cea608DataArray_ = [];
  33.     /**
  34.      * An array of CEA-708 closed caption data extracted for decoding.
  35.      * @private {!Array<!shaka.cea.Cea708Service.Cea708Byte>}
  36.      */
  37.     this.cea708DataArray_ = [];
  39.     /**
  40.      * A DTVCC Packet builder for CEA-708 data.
  41.      * @private {!shaka.cea.DtvccPacketBuilder}
  42.      */
  43.     this.dtvccPacketBuilder_ = new shaka.cea.DtvccPacketBuilder();
  45.     /**
  46.      * Number of consecutive bad frames decoded on CEA-608.
  47.      * @private {number}
  48.      */
  49.     this.badFrames_ = 0;
  51.     /**
  52.      * A map containing the stream for each mode.
  53.      * @private {!Map<string, !shaka.cea.Cea608DataChannel>}
  54.      */
  55.     this.cea608ModeToStream_ = new Map([
  56.       ['CC1', new shaka.cea.Cea608DataChannel(0, 0)], // F1 + C1 -> CC1
  57.       ['CC2', new shaka.cea.Cea608DataChannel(0, 1)], // F1 + C2 -> CC2
  58.       ['CC3', new shaka.cea.Cea608DataChannel(1, 0)], // F2 + C1 -> CC3
  59.       ['CC4', new shaka.cea.Cea608DataChannel(1, 1)], // F2 + C2 -> CC4
  60.     ]);
  62.     /**
  63.      * The current channel that is active on CEA-608 field 1.
  64.      * @private {number}
  65.      */
  66.     this.currentField1Channel_ = 0;
  68.     /**
  69.      * The current channel that is active on CEA-608 field 2.
  70.      * @private {number}
  71.      */
  72.     this.currentField2Channel_ = 0;
  74.     /**
  75.      * Map of service number to CEA-708 services, initially empty. Since there
  76.      * can be up to 63 services, they are created dynamically only when needed.
  77.      * @private {!Map<number, shaka.cea.Cea708Service>}
  78.      */
  79.     this.serviceNumberToService_ = new Map();
  81.     /**
  82.      * @private {boolean}
  83.      */
  84.     this.waitingForFirstPacket_ = true;
  86.     /**
  87.      * Set used to track available streams.
  88.      * @private {!Set.<string>}
  89.      */
  90.     this.streams_ = new Set();
  92.     this.reset();
  93.   }
  95.   /**
  96.    * Clears the decoder.
  97.    * @override
  98.    */
  99.   clear() {
  100.     shaka.log.debug('Clearing CEA decoder');
  101.     this.badFrames_ = 0;
  102.     this.cea608DataArray_ = [];
  103.     this.cea708DataArray_ = [];
  104.     this.dtvccPacketBuilder_.clear();
  105.     this.reset();
  107.     // Clear all the CEA-708 services.
  108.     for (const service of this.serviceNumberToService_.values()) {
  109.       service.clear();
  110.     }
  111.   }
  113.   /**
  114.    * Resets the decoder.
  115.    */
  116.   reset() {
  117.     shaka.log.debug('Resetting CEA decoder');
  118.     this.currentField1Channel_ = 0;
  119.     this.currentField2Channel_ = 0;
  120.     for (const stream of this.cea608ModeToStream_.values()) {
  121.       stream.reset();
  122.     }
  123.     this.waitingForFirstPacket_ = true;
  124.   }
  126.   /**
  127.    * Extracts closed caption bytes from CEA-X08 packets from the stream based on
  128.    * ANSI/SCTE 128 and A/53, Part 4.
  129.    * @override
  130.    */
  131.   extract(userDataSeiMessage, pts) {
  132.     if (this.waitingForFirstPacket_) {
  133.       shaka.log.debug('Setting first pts value to', pts);
  134.       for (const stream of this.cea608ModeToStream_.values()) {
  135.         stream.firstPts(pts);
  136.       }
  137.       this.waitingForFirstPacket_ = false;
  138.     }
  140.     const reader = new shaka.util.DataViewReader(
  141.         userDataSeiMessage, shaka.util.DataViewReader.Endianness.BIG_ENDIAN);
  143.     if (reader.getLength() < shaka.cea.CeaDecoder.MIN_LENGTH) {
  144.       return;
  145.     }
  146.     if (reader.readUint8() !== shaka.cea.CeaDecoder.USA_COUNTRY_CODE) {
  147.       return;
  148.     }
  149.     if (reader.readUint16() !== shaka.cea.CeaDecoder.ATSC_PROVIDER_CODE) {
  150.       return;
  151.     }
  152.     if (reader.readUint32() !== shaka.cea.CeaDecoder.ATSC1_USER_IDENTIFIER) {
  153.       return;
  154.     }
  156.     // user_data_type_code: 0x03 - cc_data()
  157.     if (reader.readUint8() !== 0x03) {
  158.       return;
  159.     }
  161.     // 1 bit reserved
  162.     // 1 bit process_cc_data_flag
  163.     // 1 bit zero_bit
  164.     // 5 bits cc_count
  165.     const captionData = reader.readUint8();
  166.     // If process_cc_data_flag is not set, do not process this data.
  167.     if ((captionData & 0x40) === 0) {
  168.       return;
  169.     }
  171.     const count = captionData & 0x1f;
  173.     // 8 bits reserved
  174.     reader.skip(1);
  176.     for (let i = 0; i < count; i++) {
  177.       const cc = reader.readUint8();
  178.       // When ccValid is 0, the next two bytes should be discarded.
  179.       const ccValid = (cc & 0x04) >> 2;
  180.       const ccData1 = reader.readUint8();
  181.       const ccData2 = reader.readUint8();
  183.       if (ccValid) {
  184.         const ccType = cc & 0x03;
  185.         // Send the packet to the appropriate data array (CEA-608 or CEA-708).
  186.         if (ccType === shaka.cea.CeaDecoder.NTSC_CC_FIELD_1 ||
  187.             ccType === shaka.cea.CeaDecoder.NTSC_CC_FIELD_2) {
  188.           // CEA-608 NTSC (Line 21) Data.
  189.           this.cea608DataArray_.push({
  190.             pts,
  191.             type: ccType,
  192.             ccData1,
  193.             ccData2,
  194.             order: this.cea608DataArray_.length,
  195.           });
  196.         } else {
  197.           // CEA-708 DTVCC Data.
  198.           this.cea708DataArray_.push({
  199.             pts,
  200.             type: ccType,
  201.             value: ccData1,
  202.             order: this.cea708DataArray_.length,
  203.           });
  205.           // The second byte should always be labelled as DTVCC packet data.
  206.           // Even if this pair was a DTVCC packet start, only the first byte
  207.           // contains header info, and the second byte is just packet data.
  208.           this.cea708DataArray_.push({
  209.             pts,
  210.             type: shaka.cea.DtvccPacketBuilder.DTVCC_PACKET_DATA,
  211.             value: ccData2,
  212.             order: this.cea708DataArray_.length,
  213.           });
  214.         }
  215.       }
  216.     }
  217.   }
  219.   /**
  220.    * Decodes extracted closed caption data.
  221.    * @override
  222.    */
  223.   decode() {
  224.     /** @type {!Array.<!shaka.extern.ICaptionDecoder.ClosedCaption>} */
  225.     const parsedClosedCaptions = [];
  227.     // In some versions of Chrome, and other browsers, the default sorting
  228.     // algorithm isn't stable. This comparator sorts on presentation
  229.     // timestamp, and breaks ties on receive order (position in array).
  230.     const stableComparator =
  231.       (p1, p2) => (p1.pts - p2.pts) || (p1.order - p2.order);
  233.     this.cea608DataArray_.sort(stableComparator);
  234.     this.cea708DataArray_.sort(stableComparator);
  236.     // CEA-608 packets are just byte pairs. Decode all of them.
  237.     for (const cea608Packet of this.cea608DataArray_) {
  238.       const parsedClosedCaption = this.decodeCea608_(cea608Packet);
  239.       if (parsedClosedCaption) {
  240.         parsedClosedCaptions.push(parsedClosedCaption);
  241.       }
  242.     }
  244.     // CEA-708 packets are DTVCC packets composed of many byte pairs. Add all
  245.     // byte pairs to the packet builder, and process + clear any ready packets.
  246.     for (const cea708Byte of this.cea708DataArray_) {
  247.       this.dtvccPacketBuilder_.addByte(cea708Byte);
  248.     }
  249.     const dtvccPackets = this.dtvccPacketBuilder_.getBuiltPackets();
  250.     for (const dtvccPacket of dtvccPackets) {
  251.       const closedCaptions = this.decodeCea708_(dtvccPacket);
  252.       parsedClosedCaptions.push(...closedCaptions);
  253.     }
  255.     // Clear all processed data.
  256.     this.dtvccPacketBuilder_.clearBuiltPackets();
  257.     this.cea608DataArray_ = [];
  258.     this.cea708DataArray_ = [];
  260.     return parsedClosedCaptions;
  261.   }
  263.   /**
  264.    * Decodes a CEA-608 closed caption packet based on ANSI/CEA-608.
  265.    * @param {shaka.cea.Cea608DataChannel.Cea608Packet} ccPacket
  266.    * @return {?shaka.extern.ICaptionDecoder.ClosedCaption}
  267.    * @private
  268.    */
  269.   decodeCea608_(ccPacket) {
  270.     const fieldNum = ccPacket.type;
  272.     // If this packet is a control code, then it also sets the channel.
  273.     // For control codes, cc_data_1 has the form |P|0|0|1|C|X|X|X|.
  274.     // "C" is the channel bit. It indicates whether to set C2 active.
  275.     if (shaka.cea.Cea608DataChannel.isControlCode(ccPacket.ccData1)) {
  276.       const channelNum = (ccPacket.ccData1 >> 3) & 0x01; // Get channel bit.
  278.       // Change the stream based on the field, and the new channel
  279.       if (fieldNum === 0) {
  280.         this.currentField1Channel_ = channelNum;
  281.       } else {
  282.         this.currentField2Channel_ = channelNum;
  283.       }
  284.     }
  286.     // Get the correct stream for this caption packet (CC1, ..., CC4)
  287.     const selectedChannel = fieldNum ?
  288.         this.currentField2Channel_ : this.currentField1Channel_;
  289.     const selectedMode = `CC${((fieldNum << 1) | selectedChannel) + 1}`;
  290.     const selectedStream = this.cea608ModeToStream_.get(selectedMode);
  292.     // Check for bad frames (bad pairs). This can be two 0xff, two 0x00, or any
  293.     // byte of even parity. ccData1 and ccData2 should be uint8 of odd parity.
  294.     if ((ccPacket.ccData1 === 0xff && ccPacket.ccData2 === 0xff) ||
  295.         (!ccPacket.ccData1 && !ccPacket.ccData2) ||
  296.         !this.isOddParity_(ccPacket.ccData1) ||
  297.         !this.isOddParity_(ccPacket.ccData2)) {
  298.       // Per CEA-608-B C.21, reset the memory after 45 consecutive bad frames.
  299.       if (++this.badFrames_ >= 45) {
  300.         this.reset();
  301.       }
  302.       return null;
  303.     }
  304.     this.badFrames_ = 0;
  306.     // Remove the MSB (parity bit).
  307.     ccPacket.ccData1 &= 0x7f;
  308.     ccPacket.ccData2 &= 0x7f;
  310.     // Ignore XDS
  311.     if (shaka.cea.Cea608DataChannel.isXdsControlCode(ccPacket.ccData1)) {
  312.       return null;
  313.     }
  315.     // Check for empty captions and skip them.
  316.     if (!ccPacket.ccData1 && !ccPacket.ccData2) {
  317.       return null;
  318.     }
  320.     // Process the clean CC data pair.
  321.     let parsedClosedCaption = null;
  322.     if (shaka.cea.Cea608DataChannel.isControlCode(ccPacket.ccData1)) {
  323.       this.streams_.add(selectedMode);
  324.       parsedClosedCaption = selectedStream.handleControlCode(ccPacket);
  325.     } else {
  326.       // Handle as a Basic North American Character.
  327.       selectedStream.handleBasicNorthAmericanChar(
  328.           ccPacket.ccData1, ccPacket.ccData2);
  329.     }
  331.     return parsedClosedCaption;
  332.   }
  334.   /**
  335.    * Decodes a CEA-708 DTVCC packet based on ANSI/CTA-708-E.
  336.    * @param {shaka.cea.DtvccPacket} dtvccPacket
  337.    * @return {!Array<!shaka.extern.ICaptionDecoder.ClosedCaption>}
  338.    * @private
  339.    */
  340.   decodeCea708_(dtvccPacket) {
  341.     const parsedClosedCaptions = [];
  342.     try {
  343.       while (dtvccPacket.hasMoreData()) {
  344.         // Process a service block.
  345.         const serviceBlockHeader = dtvccPacket.readByte().value;
  347.         // First 3 bits are service number, next 5 are block size,
  348.         // representing the number of bytes coming in this block
  349.         // (discluding a possible extended service block header byte)
  350.         let serviceNumber = (serviceBlockHeader & 0xe0) >> 5;
  351.         const blockSize = serviceBlockHeader & 0x1f;
  353.         if (serviceNumber === /* 0b111 */ 0x07 && blockSize != 0) {
  354.           // 2 bits null padding, 6 bits extended service number
  355.           const extendedServiceBlockHeader = dtvccPacket.readByte().value;
  356.           serviceNumber = extendedServiceBlockHeader & 0x3f;
  357.         }
  359.         // As per CEA-708-E, service number 0 is invalid, and should be ignored.
  360.         if (serviceNumber != 0) {
  361.           this.streams_.add('svc'+ serviceNumber);
  362.           // If the service doesn't already exist, create it.
  363.           if (!this.serviceNumberToService_.has(serviceNumber)) {
  364.             const service = new shaka.cea.Cea708Service(serviceNumber);
  365.             this.serviceNumberToService_.set(serviceNumber, service);
  366.           }
  367.           const service = this.serviceNumberToService_.get(serviceNumber);
  369.           // Process all control codes.
  370.           const startPos = dtvccPacket.getPosition();
  372.           // Execute this loop `blockSize` times, to decode the control codes.
  373.           while (dtvccPacket.getPosition() - startPos < blockSize) {
  374.             const closedCaption = service.handleCea708ControlCode(dtvccPacket);
  375.             if (closedCaption) {
  376.               parsedClosedCaptions.push(closedCaption);
  377.             }
  378.           }  // position < end of block
  379.         }  // serviceNumber != 0
  380.       }  // hasMoreData
  381.     } catch (error) {
  382.       if (error instanceof shaka.util.Error &&
  383.       error.code === shaka.util.Error.Code.BUFFER_READ_OUT_OF_BOUNDS) {
  384.         shaka.log.warnOnce('CEA708_INVALID_DATA',
  385.             'Buffer read out of bounds / invalid CEA-708 Data.');
  386.       } else {
  387.         // This is an unexpected error, and should be rethrown.
  388.         throw error;
  389.       }
  390.     }
  391.     return parsedClosedCaptions;
  392.   }
  394.   /**
  395.    * Checks if a byte has odd parity (Odd number of 1s in binary).
  396.    * @param {number} byte
  397.    * @return {boolean} True if the byte has odd parity.
  398.    * @private
  399.    */
  400.   isOddParity_(byte) {
  401.     let parity = 0;
  402.     while (byte) {
  403.       parity ^= (byte & 1); // toggle parity if low bit is 1
  404.       byte >>= 1; // shift away the low bit
  405.     }
  406.     return parity === 1;
  407.   }
  409.   /**
  410.    * Returns the streams that the CEA decoder found.
  411.    *
  412.    * @override
  413.    */
  414.   getStreams() {
  415.     return Array.from(this.streams_);
  416.   }
  417. };
  419. /**
  420.  * itu_t_35_provider_code for ATSC user_data
  421.  * @private @const {number}
  422.  */
  423. shaka.cea.CeaDecoder.ATSC_PROVIDER_CODE = 0x0031;
  425. /**
  426.  * When provider is ATSC user data, the ATSC_user_identifier code
  427.  * for ATSC1_data is "GA94" (0x47413934)
  428.  * @private @const {number}
  429.  */
  430. shaka.cea.CeaDecoder.ATSC1_USER_IDENTIFIER = 0x47413934;
  432. /**
  433.  * @private @const {number}
  434.  */
  435. shaka.cea.CeaDecoder.NTSC_CC_FIELD_1 = 0;
  437. /**
  438.  * @private @const {number}
  439.  */
  440. shaka.cea.CeaDecoder.NTSC_CC_FIELD_2 = 1;
  442. /**
  443.  * 0xB5 is USA's code (Rec. ITU-T T.35)
  444.  * @private @const {number}
  445.  */
  446. shaka.cea.CeaDecoder.USA_COUNTRY_CODE = 0xb5;
  448. /**
  449.  * Caption packet min length
  450.  * Country Code + ATSC_PROVIDER_CODE + ATSC_1_USER_IDENTIFIER + USER_DATA_TYPE
  451.  * @private @const {number}
  452.  */
  453. shaka.cea.CeaDecoder.MIN_LENGTH = 8;
  455. shaka.media.ClosedCaptionParser.registerDecoder(
  456.     () => new shaka.cea.CeaDecoder());