Source: lib/cea/cea_decoder.js

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