@svta/cml-608 1.1.0 → 1.1.1

package/README.md

@@ -16,37 +16,41 @@ import { CaptionScreen, Row } from "@svta/cml-608";
 
 ### Extracting captions from a media sample
 
-CTA-608 captions ride inside the video elementary stream as an ATSC A/53 `cc_data()`
-payload. The payload is the same for every codec; only the envelope around it differs, so
-pick the extractor that matches the sample entry type:
+CTA-608 captions are embedded in the video elementary stream as an ATSC A/53 `cc_data()`
+payload. Only the envelope around the payload differs by codec. The envelope is either a
+SEI message in a NAL unit, or an OBU. Choose the extractor that matches the sample entry
+type:
 
 | Sample entry            | Envelope                          | Extractor                          |
 | ----------------------- | --------------------------------- | ---------------------------------- |
 | `avc1` / `hvc1` / `vvc1` | `itu_t_t35` SEI message in a NAL  | `extractCta608DataFromSample`      |
 | `av01`                  | `metadata_itu_t_t35` OBU          | `extractCta608DataFromAv1Sample`   |
 
-Both return the same `[field1, field2]` byte arrays, which `Cta608Parser` turns into
-rendered caption screens:
+Both extractors return the same `[field1, field2]` byte arrays. `Cta608Parser` renders
+them as caption screens:
 
 ```typescript
 import { Cta608Parser, extractCta608DataFromAv1Sample } from "@svta/cml-608";
+import type { CaptionScreen } from "@svta/cml-608";
 
 const parser = new Cta608Parser(1, {
-	newCue(startTime, endTime, screen) {
+	newCue(startTime: number, endTime: number, screen: CaptionScreen) {
 		console.log(startTime, endTime, screen.getDisplayText());
 	},
 }, null);
 
-const [field1] = extractCta608DataFromAv1Sample(view, samplePos, sampleSize);
-if (field1.length) {
-	parser.addData(sampleTimeMs, field1);
+// Call once per AV1 sample. The sample starts at samplePos in view.
+function onSample(view: DataView, samplePos: number, sampleSize: number, sampleTimeMs: number): void {
+	const [field1] = extractCta608DataFromAv1Sample(view, samplePos, sampleSize);
+	if (field1.length) {
+		parser.addData(sampleTimeMs, field1);
+	}
 }
 ```
 
-These are separate functions rather than one auto-detecting call because the two carriages
-are framed differently and neither sample announces which it is. A NAL unit sample puts a
-fixed-width big-endian length in front of each unit, and that width is only known from
-`lengthSizeMinusOne` in the `avcC`/`hvcC` config. An AV1 sample uses the low-overhead
-format, where each OBU carries its own `obu_size` after the header — and may omit it on
-the last OBU. Either way the framing has to come from the sample entry, so pass the bytes
-to the extractor that matches it.
+The two extractors are separate because the two envelopes are framed differently, and a
+sample does not announce its framing. A NAL unit sample puts a fixed-width big-endian
+length before each unit. Only `lengthSizeMinusOne` in the `avcC` or `hvcC` config gives
+that width. An AV1 sample uses the low-overhead format. Each OBU has its own `obu_size`
+after the header, and the last OBU may omit it. In both cases the sample entry gives the
+framing.

package/dist/index.d.ts

@@ -1,24 +1,22 @@
 import { ValueOf } from "@svta/cml-utils";
-
 //#region src/CaptionModes.d.ts
-
 /**
-* The different caption modes that can be used.
-*
-* @public
-*/
+ * The different caption modes that can be used.
+ *
+ * @public
+ */
 type CaptionModes = "MODE_ROLL-UP" | "MODE_POP-ON" | "MODE_PAINT-ON" | "MODE_TEXT" | null;
 //#endregion
 //#region src/VerboseLevel.d.ts
 /**
-* Logging levels for the CTA-608 parser.
-*
-*
-* @enum
-*
-* @public
-*/
-declare const VerboseLevel: {
+ * Logging levels for the CTA-608 parser.
+ *
+ *
+ * @enum
+ *
+ * @public
+ */
+export declare const VerboseLevel: {
   readonly ERROR: 0;
   readonly TEXT: 1;
   readonly WARNING: 2;
@@ -27,18 +25,17 @@ declare const VerboseLevel: {
   readonly DATA: 3;
 };
 /**
-* @public
-*/
-type VerboseLevel = ValueOf<typeof VerboseLevel>;
+ * @public
+ */
+export type VerboseLevel = ValueOf<typeof VerboseLevel>;
 //#endregion
 //#region src/CaptionsLogger.d.ts
-
 /**
-* CaptionsLogger. To be removed in the future.
-*
-* @public
-*/
-declare class CaptionsLogger {
+ * CaptionsLogger. To be removed in the future.
+ *
+ * @public
+ */
+export declare class CaptionsLogger {
   time: number | null;
   verboseLevel: VerboseLevel;
   log(severity: VerboseLevel, msg: string | (() => string)): void;
@@ -46,11 +43,11 @@ declare class CaptionsLogger {
 //#endregion
 //#region src/PACData.d.ts
 /**
-* Represents a single PAC (Preamble Address Code) data.
-*
-* @public
-*/
-type PACData = {
+ * Represents a single PAC (Preamble Address Code) data.
+ *
+ * @public
+ */
+export type PACData = {
   row: number;
   indent: number | null;
   color: string | null;
@@ -60,11 +57,11 @@ type PACData = {
 //#endregion
 //#region src/PenStyles.d.ts
 /**
-* PenStyles
-*
-* @public
-*/
-type PenStyles = {
+ * PenStyles
+ *
+ * @public
+ */
+export type PenStyles = {
   foreground: string | null;
   underline: boolean;
   italics: boolean;
@@ -73,13 +70,12 @@ type PenStyles = {
 };
 //#endregion
 //#region src/PenState.d.ts
-
 /**
-* Pen state.
-*
-* @public
-*/
-declare class PenState {
+ * Pen state.
+ *
+ * @public
+ */
+export declare class PenState {
   foreground: string;
   underline: boolean;
   italics: boolean;
@@ -93,13 +89,12 @@ declare class PenState {
 }
 //#endregion
 //#region src/StyledUnicodeChar.d.ts
-
 /**
-* Unicode character with styling and background.
-*
-* @public
-*/
-declare class StyledUnicodeChar {
+ * Unicode character with styling and background.
+ *
+ * @public
+ */
+export declare class StyledUnicodeChar {
   uchar: string;
   penState: PenState;
   reset(): void;
@@ -112,11 +107,11 @@ declare class StyledUnicodeChar {
 //#endregion
 //#region src/Row.d.ts
 /**
-* CTA-608 row consisting of NR_COLS instances of StyledUnicodeChar.
-*
-* @public
-*/
-declare class Row {
+ * CTA-608 row consisting of NR_COLS instances of StyledUnicodeChar.
+ *
+ * @public
+ */
+export declare class Row {
   chars: StyledUnicodeChar[];
   cueStartTime: number | null;
   private pos;
@@ -127,16 +122,16 @@ declare class Row {
   copy(other: Row): void;
   isEmpty(): boolean;
   /**
-  *  Set the cursor to a valid column.
-  */
+   *  Set the cursor to a valid column.
+   */
   setCursor(absPos: number): void;
   /**
-  * Move the cursor relative to current position.
-  */
+   * Move the cursor relative to current position.
+   */
   moveCursor(relPos: number): void;
   /**
-  * Backspace, move one step back and clear character.
-  */
+   * Backspace, move one step back and clear character.
+   */
   backSpace(): void;
   insertChar(byte: number): void;
   clearFromPos(startPos: number): void;
@@ -148,11 +143,11 @@ declare class Row {
 //#endregion
 //#region src/CaptionScreen.d.ts
 /**
-* Keep a CTA-608 screen of 32x15 styled characters
-*
-* @public
-*/
-declare class CaptionScreen {
+ * Keep a CTA-608 screen of 32x15 styled characters
+ *
+ * @public
+ */
+export declare class CaptionScreen {
   rows: Row[];
   private currRow;
   private nrRollUpRows;
@@ -166,33 +161,33 @@ declare class CaptionScreen {
   backSpace(): void;
   clearToEndOfRow(): void;
   /**
-  * Insert a character (without styling) in the current row.
-  */
+   * Insert a character (without styling) in the current row.
+   */
   insertChar(char: number): void;
   setPen(styles: Partial<PenStyles>): void;
   moveCursor(relPos: number): void;
   setCursor(absPos: number): void;
   setPAC(pacData: PACData): void;
   /**
-  * Set background/extra foreground, but first do back_space, and then insert space (backwards compatibility).
-  */
+   * Set background/extra foreground, but first do back_space, and then insert space (backwards compatibility).
+   */
   setBkgData(bkgData: Partial<PenStyles>): void;
   setRollUpRows(nrRows: number | null): void;
   rollUp(): void;
   /**
-  * Get all non-empty rows with as unicode text.
-  */
+   * Get all non-empty rows with as unicode text.
+   */
   getDisplayText(asOneRow?: boolean): string;
   getTextAndFormat(): Row[];
 }
 //#endregion
 //#region src/CueHandler.d.ts
 /**
-* A handler for CTA-608 cues.
-*
-* @public
-*/
-type CueHandler = {
+ * A handler for CTA-608 cues.
+ *
+ * @public
+ */
+export type CueHandler = {
   newCue(startTime: number, endTime: number, screen: CaptionScreen): void;
   reset?(): void;
   dispatchCue?(): void;
@@ -200,11 +195,11 @@ type CueHandler = {
 //#endregion
 //#region src/Cta608Channel.d.ts
 /**
-* CTA-608 Channel
-*
-* @public
-*/
-declare class Cta608Channel {
+ * CTA-608 Channel
+ *
+ * @public
+ */
+export declare class Cta608Channel {
   chNr: number;
   outputFilter: CueHandler;
   mode: CaptionModes;
@@ -245,19 +240,19 @@ declare class Cta608Channel {
 //#endregion
 //#region src/SupportedField.d.ts
 /**
-* SupportedField
-*
-* @public
-*/
-type SupportedField = 1 | 3;
+ * SupportedField
+ *
+ * @public
+ */
+export type SupportedField = 1 | 3;
 //#endregion
 //#region src/Cta608Parser.d.ts
 /**
-* CEA-608 caption parser.
-*
-* @public
-*/
-declare class Cta608Parser {
+ * CEA-608 caption parser.
+ *
+ * @public
+ */
+export declare class Cta608Parser {
   private channels;
   private currentChannel;
   private cmdHistory;
@@ -265,174 +260,174 @@ declare class Cta608Parser {
   private lastTime;
   constructor(field: SupportedField, out1: any, out2: any);
   /**
-  * Add data for time t in forms of list of bytes (unsigned ints). The bytes are treated as pairs.
-  *
-  * @param time - The time in milliseconds
-  * @param byteList - The list of bytes
-  */
+   * Add data for time t in forms of list of bytes (unsigned ints). The bytes are treated as pairs.
+   *
+   * @param time - The time in milliseconds
+   * @param byteList - The list of bytes
+   */
   addData(time: number | null, byteList: number[]): void;
   /**
-  * Parse Command.
-  *
-  * @param a - The first byte
-  * @param b - The second byte
-  * @returns True if a command was found
-  */
+   * Parse Command.
+   *
+   * @param a - The first byte
+   * @param b - The second byte
+   * @returns True if a command was found
+   */
   private parseCmd;
   /**
-  * Parse midrow styling command
-  *
-  * @param a - The first byte
-  * @param b - The second byte
-  * @returns `true` if midrow styling command was found
-  */
+   * Parse midrow styling command
+   *
+   * @param a - The first byte
+   * @param b - The second byte
+   * @returns `true` if midrow styling command was found
+   */
   private parseMidrow;
   /**
-  * Parse Preable Access Codes (Table 53).
-  *
-  * @param a - The first byte
-  * @param b - The second byte
-  * @returns A Boolean that tells if PAC found
-  */
+   * Parse Preable Access Codes (Table 53).
+   *
+   * @param a - The first byte
+   * @param b - The second byte
+   * @returns A Boolean that tells if PAC found
+   */
   private parsePAC;
   /**
-  * Interpret the second byte of the pac, and return the information.
-  *
-  * @param row - The row number
-  * @param byte - The second byte
-  * @returns pacData with style parameters
-  */
+   * Interpret the second byte of the pac, and return the information.
+   *
+   * @param row - The row number
+   * @param byte - The second byte
+   * @returns pacData with style parameters
+   */
   private interpretPAC;
   /**
-  * Parse characters.
-  *
-  * @param a - The first byte
-  * @param b - The second byte
-  * @returns An array with 1 to 2 codes corresponding to chars, if found. null otherwise.
-  */
+   * Parse characters.
+   *
+   * @param a - The first byte
+   * @param b - The second byte
+   * @returns An array with 1 to 2 codes corresponding to chars, if found. null otherwise.
+   */
   private parseChars;
   /**
-  * Parse extended background attributes as well as new foreground color black.
-  *
-  * @param a - The first byte
-  * @param b - The second byte
-  * @returns True if background attributes are found
-  */
+   * Parse extended background attributes as well as new foreground color black.
+   *
+   * @param a - The first byte
+   * @param b - The second byte
+   * @returns True if background attributes are found
+   */
   private parseBackgroundAttributes;
   /**
-  * Reset state of parser and its channels.
-  */
+   * Reset state of parser and its channels.
+   */
   reset(): void;
   /**
-  * Trigger the generation of a cue, and the start of a new one if displayScreens are not empty.
-  */
+   * Trigger the generation of a cue, and the start of a new one if displayScreens are not empty.
+   */
   cueSplitAtTime(t: number): void;
 }
 //#endregion
 //#region src/extractCta608Data.d.ts
 /**
-* Extract CTA-608 data from a DataView
-*
-* @param raw - The DataView to extract the data from
-* @param cta608Range - The range of the CTA-608 data
-* @returns The extracted CTA-608 data
-*
-* @public
-*/
-declare function extractCta608Data(raw: DataView, cta608Range: number[]): number[][];
+ * Extract CTA-608 data from a DataView
+ *
+ * @param raw - The DataView to extract the data from
+ * @param cta608Range - The range of the CTA-608 data
+ * @returns The extracted CTA-608 data
+ *
+ * @public
+ */
+export declare function extractCta608Data(raw: DataView, cta608Range: number[]): number[][];
 //#endregion
 //#region src/extractCta608DataFromAv1Sample.d.ts
 /**
-* Extracts CTA-608 data from an AV1 (`av01`) sample.
-*
-* AV1 has no NAL units, so captions ride in an `metadata_itu_t_t35` OBU rather than in
-* an SEI message. The caption payload is unchanged — the same A/53 `cc_data()` under the
-* same T.35/GA94 identifier that {@link extractCta608DataFromSample} reads — so the
-* returned field data feeds {@link Cta608Parser} identically.
-*
-* This is a separate function rather than a codec branch inside
-* {@link extractCta608DataFromSample} because the two carriages are framed differently and
-* neither sample is self-identifying. A NAL unit sample puts a fixed-width big-endian
-* length in front of each unit, and that width is only known from `lengthSizeMinusOne` in
-* the `avcC`/`hvcC` config. An AV1 sample uses the low-overhead format, where each OBU
-* carries its own `obu_size` after the header — and may omit it on the last OBU. Select on
-* the sample entry type (`av01`) instead.
-*
-* @param raw - The DataView with media data
-* @param startPos - The start position of the sample within the DataView
-* @param sampleSize - The size of the sample in bytes
-* @returns fieldData array containing field 1 and field 2 data arrays
-*
-* @example
-* {@includeCode ../test/extractCta608DataFromAv1Sample.test.ts#example}
-*
-* @public
-*/
-declare function extractCta608DataFromAv1Sample(raw: DataView, startPos: number, sampleSize: number): number[][];
+ * Extracts CTA-608 data from an AV1 (`av01`) sample.
+ *
+ * AV1 has no NAL units, so captions ride in an `metadata_itu_t_t35` OBU rather than in
+ * an SEI message. The caption payload is unchanged — the same A/53 `cc_data()` under the
+ * same T.35/GA94 identifier that {@link extractCta608DataFromSample} reads — so the
+ * returned field data feeds {@link Cta608Parser} identically.
+ *
+ * This is a separate function rather than a codec branch inside
+ * {@link extractCta608DataFromSample} because the two carriages are framed differently and
+ * neither sample is self-identifying. A NAL unit sample puts a fixed-width big-endian
+ * length in front of each unit, and that width is only known from `lengthSizeMinusOne` in
+ * the `avcC`/`hvcC` config. An AV1 sample uses the low-overhead format, where each OBU
+ * carries its own `obu_size` after the header — and may omit it on the last OBU. Select on
+ * the sample entry type (`av01`) instead.
+ *
+ * @param raw - The DataView with media data
+ * @param startPos - The start position of the sample within the DataView
+ * @param sampleSize - The size of the sample in bytes
+ * @returns fieldData array containing field 1 and field 2 data arrays
+ *
+ * @example
+ * {@includeCode ../test/extractCta608DataFromAv1Sample.test.ts#example}
+ *
+ * @public
+ */
+export declare function extractCta608DataFromAv1Sample(raw: DataView, startPos: number, sampleSize: number): number[][];
 //#endregion
 //#region src/extractCta608DataFromSample.d.ts
 /**
-* Extracts CEA-608 data from a given sample.
-*
-* @param raw - The DataView with media data
-* @param startPos - The start position within the DataView
-* @param sampleSize - The size of the sample in bytes
-* @returns fieldData array containing field 1 and field 2 data arrays
-*
-* @public
-*/
-declare function extractCta608DataFromSample(raw: DataView, startPos: number, sampleSize: number): number[][];
+ * Extracts CEA-608 data from a given sample.
+ *
+ * @param raw - The DataView with media data
+ * @param startPos - The start position within the DataView
+ * @param sampleSize - The size of the sample in bytes
+ * @returns fieldData array containing field 1 and field 2 data arrays
+ *
+ * @public
+ */
+export declare function extractCta608DataFromSample(raw: DataView, startPos: number, sampleSize: number): number[][];
 //#endregion
 //#region src/findCta608Nalus.d.ts
 /**
-* Find CTA-608 NAL units in a video stream
-*
-* @param raw - The DataView to extract the data from
-* @param startPos - The start position of the data
-* @param size - The size of the data
-* @returns The extracted CTA-608 NAL units
-*
-* @public
-*/
-declare function findCta608Nalus(raw: DataView, startPos: number, size: number): number[][];
+ * Find CTA-608 NAL units in a video stream
+ *
+ * @param raw - The DataView to extract the data from
+ * @param startPos - The start position of the data
+ * @param size - The size of the data
+ * @returns The extracted CTA-608 NAL units
+ *
+ * @public
+ */
+export declare function findCta608Nalus(raw: DataView, startPos: number, size: number): number[][];
 //#endregion
 //#region src/SccParser.d.ts
 /**
-* The copyright in this software is being made available under the BSD License,
-* included below. This software may be subject to other third party and contributor
-* rights, including patent rights, and no such rights are granted under this license.
-*
-* Copyright (c) 2015-2016, DASH Industry Forum.
-* All rights reserved.
-*
-* Redistribution and use in source and binary forms, with or without modification,
-* are permitted provided that the following conditions are met:
-*  1. Redistributions of source code must retain the above copyright notice, this
-*  list of conditions and the following disclaimer.
-*  * Redistributions in binary form must reproduce the above copyright notice,
-*  this list of conditions and the following disclaimer in the documentation and/or
-*  other materials provided with the distribution.
-*  2. Neither the name of Dash Industry Forum nor the names of its
-*  contributors may be used to endorse or promote products derived from this software
-*  without specific prior written permission.
-*
-*  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS AS IS AND ANY
-*  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-*  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-*  IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
-*  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-*  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
-*  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
-*  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-*  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-*  POSSIBILITY OF SUCH DAMAGE.
-*/
+ * The copyright in this software is being made available under the BSD License,
+ * included below. This software may be subject to other third party and contributor
+ * rights, including patent rights, and no such rights are granted under this license.
+ *
+ * Copyright (c) 2015-2016, DASH Industry Forum.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification,
+ * are permitted provided that the following conditions are met:
+ *  1. Redistributions of source code must retain the above copyright notice, this
+ *  list of conditions and the following disclaimer.
+ *  * Redistributions in binary form must reproduce the above copyright notice,
+ *  this list of conditions and the following disclaimer in the documentation and/or
+ *  other materials provided with the distribution.
+ *  2. Neither the name of Dash Industry Forum nor the names of its
+ *  contributors may be used to endorse or promote products derived from this software
+ *  without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS AS IS AND ANY
+ *  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ *  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *  IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+ *  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ *  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+ *  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ *  POSSIBILITY OF SUCH DAMAGE.
+ */
 /**
-* SCC Parser
-*
-* @public
-*/
-declare class SccParser {
+ * SCC Parser
+ *
+ * @public
+ */
+export declare class SccParser {
   hasHeader: boolean;
   nrLinesParsed: number;
   processor: any;
@@ -446,5 +441,5 @@ declare class SccParser {
   getLinesParsed(): number;
 }
 //#endregion
-export { CaptionModes, CaptionScreen, CaptionsLogger, Cta608Channel, Cta608Parser, CueHandler, PACData, PenState, PenStyles, Row, SccParser, StyledUnicodeChar, SupportedField, VerboseLevel, extractCta608Data, extractCta608DataFromAv1Sample, extractCta608DataFromSample, findCta608Nalus };
+export type { CaptionModes };
 //# sourceMappingURL=index.d.ts.map