@aim-packages/subtitle 0.0.19 → 0.1.0

package/dist/index.d.ts

@@ -67,319 +67,458 @@ export declare interface AimSegments {
 
 declare function assToAimSegments(text: string): Promise<AimSegments[]>;
 
-declare function chunkArrayStrings(strings: string[], characterLimit: number): string[];
-
-declare function chunkSegmentStringsWithIndex(segments: AimSegments[], characterLimit: number): {
-    segmentsResult: AimSegments[][];
-    stringResult: string[];
-    indexStringResult: string[];
-    indexResult: number[];
-};
-
-declare function consolidateSegments(items: Segment[], option: {
-    maxDistance: number;
-    padding: number;
-}): Segment[] | undefined;
-
 /**
- * 匹配中文、日文、韩文字符的正则表达式
+ * 将字符串数组按字符限制分块
  *
- * @export
- * @param {string} str
- * @return {*}  {boolean}
- */
-declare function containsCJKCharacters(str: string): boolean;
-
-/**
- * Convert a HH:MM:SS,MMM or HH:MM:SS.MMM time format into seconds.
+ * 作用：
+ * 1. 将字符串数组按照字符限制进行分块，避免单次处理内容过多
+ * 2. 使用换行符连接同一分块内的字符串
+ * 3. 在分块时会预留一定的字符空间（10个字符）用于换行符和格式调整
  *
  * @export
- * @param {string} time - The time to be converted.
- * @return {*}  {number} - The time converted to seconds.
- */
-declare function convertToSeconds(time?: string): number;
-
-/**
- * Creates a new Parser parser.
- *
- * @param onParse - Callback to invoke when a new event is parsed, or a new reconnection interval
- *                  has been sent from the server
- *
- * @returns A new Parser parser, with `parse`, `end` and `reset` methods.
- * @public
+ * @param {string[]} strings - 输入的字符串数组
+ * @param {number} characterLimit - 每个分块的最大字符数限制
+ * @return {string[]} 分块后的字符串数组，每个元素是换行符分隔的文本块
  */
-declare function create(options?: ParserOptions<AimSegments[], AimSegments[], string> & {
-    vad?: Segment[];
-    vadPadding?: [number, number];
-}): Parser<string>;
-
-declare function create_2(options?: ParserOptions<RequiredByKey<Partial<AimSegments>, "index">[], Partial<AimSegments>[], string>): Parser<string>;
-
-declare function create_3(options?: ParserOptions<AimSegments[], AimSegments[], AimSegments[]> & {
-    sentenceLength?: number;
-    repeatString?: string[];
-}): Parser<AimSegments[]>;
-
-declare function detectAllLanguage(text: string): LanguageDetectionResultsEntry[];
-
-declare function detectLanguage(text: string): LanguageDetectionResultsEntry;
-
-export declare namespace filter {
-    export {
-        StreamFilter
-    }
-}
+declare function chunkArrayStrings(strings: string[], characterLimit: number): string[];
 
 /**
- * 将秒数转换为 xx:xx:xx.xxx 格式
+ * 将字幕片段按字符限制分块，并生成多种格式的结果
  *
- * @export
- * @param {number} seconds
- * @return {*}  {string}
- */
-declare function formatTime(seconds: number): string;
-
-export declare type LanguageCode = "auto" | "none" | "zh" | "zh_cn" | "zh_tw" | "yue" | "en" | "ja" | "ko" | "fr" | "es" | "ru" | "de" | "it" | "tr" | "pt" | "vi" | "id" | "th" | "ms" | "ar" | "hi" | "ro" | "ug" | "uz" | "kk" | "az" | "ky" | "fa" | "tg";
-
-/**
- * 将语言代码转换为名称
+ * 作用：
+ * 1. 将字幕片段数组按照字符限制分块，避免单次处理内容过多
+ * 2. 为每个片段添加索引信息，便于后续处理和追踪
+ * 3. 生成多种格式的分块结果，满足不同场景的需求
  *
  * @export
- * @param {LanguageCode} languageCode
- * @return {*}
- */
-declare function languageCodeToName(languageCode: LanguageCode): string;
-
-declare interface LanguageDetectionResultsEntry {
-    language: LanguageCode;
-    languageName: string;
-    probability: number;
-}
-
-declare interface OpenAIResult {
-    task: string;
-    language: string;
-    text: string;
-    words: {
-        word: string;
-        start: number;
-        end: number;
-    }[];
-    segments: {
-        text: string;
-        start: number;
-        end: number;
-    }[];
-}
-
-declare function openaiToAimSegments(json: OpenAIResult): Promise<AimSegments[]>;
-
-export declare interface OptimizationOptions {
-    emt: boolean;
-    ep: boolean;
-    zf: boolean;
-    punc: boolean;
-    em: boolean;
-    space: boolean;
-    repeat: boolean;
-}
-
-/**
- * 为数字前方自动补0到特定的位数，默认两位
- */
-declare function padNumber(num: number, length?: number): string;
-
-/**
- * Callback passed as the `onParse` callback to a parser
- *
- * @public
- */
-declare type ParseCallback<T> = (event: ParsedEvent<T>) => void;
-
-declare interface ParsedEvent<T> {
-    type: "event";
-    event: "start" | "message" | "end";
-    data?: T;
-}
-
-/**
- * Parser parser instance.
- *
- * Needs to be reset between reconnections/when switching data source, using the `reset()` method.
- *
- * @public
- */
-declare interface Parser<T = string> {
-    /**
-     * Feeds the parser another chunk. The method _does not_ return a parsed message.
-     * Instead, if the chunk was a complete message (or completed a previously incomplete message),
-     * it will invoke the `onParse` callback used to create the parsers.
-     *
-     * @param chunk - The chunk to parse. Can be a partial, eg in the case of streaming messages.
-     * @public
-     */
-    feed(chunk: T): void;
-    /**
-     * Resets the parser state. This is required when you have a new stream of messages -
-     * for instance in the case of a client being disconnected and reconnecting.
-     *
-     * @public
-     */
-    reset(): void;
-    end(): void;
-}
-
-export declare namespace parser {
-    export {
-        srtToAimSegments,
-        vttToAimSegments,
-        assToAimSegments,
-        tingwuToAimSegments,
-        openaiToAimSegments,
-        create as createWhisperStreamParser,
-        create_2 as createTranslateStreamParser,
-        create_3 as createSegmentStreamParser
-    }
-}
-
-/**
- * `ParserOptions` 是一个泛型类型，用于配置解析器的回调函数。
- *
- * @template S - 解析开始时的状态类型
- * @template P - 解析过程中使用的状态类型
- * @template E - 解析结束时的状态类型
- *
- * @property {ParseCallback<S>} [onStart] - 解析开始时的回调函数
- * @property {ParseCallback<P>} [onParse] - 解析过程中调用的回调函数
- * @property {ParseCallback<P>} [onProgress] - 解析进度更新时的回调函数
- * @property {ParseCallback<E>} [onEnd] - 解析结束时的回调函数
- */
-declare type ParserOptions<S, P, E> = {
-    onStart?: ParseCallback<S>;
-    onParse?: ParseCallback<P>;
-    onProgress?: ParseCallback<P>;
-    onEnd?: ParseCallback<E>;
-};
-
-export declare type PartialByKey<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-
-declare class RepeatCheck {
-    threshold: number;
-    hit: number;
-    prevSegment?: AimSegments;
-    hitSegment?: AimSegments;
-    hitSegmentList: AimSegments[];
-    options: RepeatCheckOption;
-    constructor(options?: RepeatCheckOption);
-    push(segment: AimSegments): void;
-    end(): void;
-    reset(): void;
-}
-
-declare interface RepeatCheckOption {
-    onHit?: (segment: AimSegments[]) => void;
-}
-
-export declare type RequiredByKey<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
-
-export declare type Segment = {
-    start: number;
-    end: number;
-};
-
-declare function splitToSentences(text: string, languageCode?: LanguageCode): string[];
-
-declare function srtToAimSegments(text: string): Promise<AimSegments[]>;
-
-declare class StreamFilter {
-    chains: Record<string, any>;
-    delimit: string;
-    onFilter?: (text: string) => any;
-    checked: boolean;
-    checkedText: string;
-    checkedLevel?: Record<string, any>;
-    filteredText: string;
-    constructor(onFilter?: (text: string) => any);
-    add(keyword: string, replaceText?: string): void;
-    parse(data: [string, string][]): void;
-    reParse(data: string[][]): void;
-    feed(c: string): void;
-    feedAll(text: string): string;
-    end(): string;
-}
-
-declare function subtitleOptimization(segments: AimSegments[], options?: OptimizationOptions): {
-    result: {
-        emt: number[];
-        ep: number[];
-        zf: number[];
-        punc: number[];
-        em: number[];
-        space: number[];
-        repeat: number[];
-    };
-    repeat: AimSegments[];
-    segments: AimSegments[];
-};
-
-declare const subtitleOptimizationRegExp: {
-    punc: RegExp;
-    em: RegExp;
-    space: RegExp;
-    ep: RegExp;
-};
-
-declare interface TingwuResult {
-    TaskId: string;
-    Transcription: {
-        AudioInfo: {
-            "Size": number;
-            "Duration": number;
-            "SampleRate": number;
-            "Language": string;
-        };
-        Paragraphs: {
-            ParagraphId: string;
-            SpeakerId: string;
-            Words: {
-                "Id": number;
-                "SentenceId": number;
-                "Start": number;
-                "End": number;
-                "Text": string;
-            }[];
-        }[];
-    };
-}
-
-declare function tingwuToAimSegments(json: TingwuResult): Promise<AimSegments[]>;
-
-export declare namespace tools {
-    export {
-        subtitleOptimization,
-        RepeatCheckOption,
-        RepeatCheck,
-        subtitleOptimizationRegExp,
-        detectAllLanguage,
-        detectLanguage,
-        LanguageDetectionResultsEntry,
-        splitToSentences
-    }
-}
-
-export declare namespace utils {
-    export {
-        padNumber,
-        formatTime,
-        convertToSeconds,
-        containsCJKCharacters,
-        languageCodeToName,
-        chunkArrayStrings,
-        chunkSegmentStringsWithIndex,
-        consolidateSegments
-    }
-}
-
-declare function vttToAimSegments(text: string): Promise<AimSegments[]>;
-
-export { }
+ * @param {AimSegments[]} segments - 输入的字幕片段数组
+ * @param {number} characterLimit - 每个分块的最大字符数限制
+ * @return {{
+         *   segmentsResult: AimSegments[][] - 分块后的字幕片段数组，每个元素是一个片段数组
+         *   stringResult: string[] - 纯文本分块结果，每个元素是换行符分隔的文本
+         *   indexStringResult: string[] - 带索引的文本分块结果，格式为 [索引]文本
+         *   indexResult: number[] - 每个分块的起始索引数组，用于追踪分块边界
+         * }} 分块处理的结果对象
+         */
+     declare function chunkSegmentStringsWithIndex(segments: AimSegments[], characterLimit: number): {
+         segmentsResult: AimSegments[][];
+         stringResult: string[];
+         indexStringResult: string[];
+         indexResult: number[];
+     };
+
+     /**
+      * 合并字幕片段，优化字幕的时间轴
+      *
+      * 作用：
+      * 1. 将时间间隔小于 maxDistance 的相邻字幕片段合并为一个片段
+      * 2. 可选择性地为每个片段添加 padding 时间，扩展片段的开始和结束时间
+      * 3. 如果添加了 padding，会自动处理重叠的片段，将它们合并
+      *
+      * @export
+      * @param {Segment[]} items - 输入的字幕片段数组，每个片段包含 start 和 end 时间
+      * @param {{
+              *   maxDistance: number - 最大时间间隔，小于此值的相邻片段会被合并
+              *   padding: number - 可选的时间填充，为每个片段扩展开始和结束时间
+              * }} option - 合并选项
+              * @return {Segment[]} 合并后的字幕片段数组，如果输入为空则返回空数组
+              */
+          declare function consolidateSegments(items: Segment[], option: {
+              maxDistance: number;
+              padding: number;
+          }): Segment[] | undefined;
+
+          /**
+           * 匹配中文、日文、韩文字符的正则表达式
+           *
+           * @export
+           * @param {string} str
+           * @return {*}  {boolean}
+           */
+          declare function containsCJKCharacters(str: string): boolean;
+
+          /**
+           * Convert a HH:MM:SS,MMM or HH:MM:SS.MMM time format into seconds.
+           *
+           * @export
+           * @param {string} time - The time to be converted.
+           * @return {*}  {number} - The time converted to seconds.
+           */
+          declare function convertToSeconds(time?: string): number;
+
+          /**
+           * Creates a new Parser parser.
+           *
+           * @param onParse - Callback to invoke when a new event is parsed, or a new reconnection interval
+           *                  has been sent from the server
+           *
+           * @returns A new Parser parser, with `parse`, `end` and `reset` methods.
+           * @public
+           */
+          declare function create(options?: ParserOptions<AimSegments[], AimSegments[], string> & {
+              vad?: Segment[];
+              vadPadding?: [number, number];
+          }): Parser<string>;
+
+          declare function create_2(options?: ParserOptions<RequiredByKey<Partial<AimSegments>, "index">[], Partial<AimSegments>[], string>): Parser<string>;
+
+          declare function create_3(options?: ParserOptions<AimSegments[], AimSegments[], AimSegments[]> & {
+              sentenceLength?: number;
+              repeatString?: string[];
+          }): Parser<AimSegments[]>;
+
+          /**
+           * 检测文本中的所有可能语言
+           * 使用 tinyld 库进行多语言检测，返回按概率排序的语言列表
+           *
+           * @param {string} text - 需要检测语言的文本内容
+           * @return {LanguageDetectionResultsEntry[]} 返回检测到的所有语言及其概率，按概率从高到低排序
+           *
+           * @example
+           * ```typescript
+           * const results = detectAllLanguage("Hello world 你好世界");
+           * // 返回: [
+           * //   { language: 'en', languageName: 'English', probability: 0.8 },
+           * //   { language: 'zh', languageName: '中文', probability: 0.2 }
+           * // ]
+           * ```
+           */
+          declare function detectAllLanguage(text: string): LanguageDetectionResultsEntry[];
+
+          /**
+           * 检测文本的主要语言
+           * 使用 tinyld 库进行单语言检测，返回最可能的语言
+           *
+           * @param {string} text - 需要检测语言的文本内容
+           * @return {LanguageDetectionResultsEntry} 返回检测到的主要语言信息
+           *
+           * @example
+           * ```typescript
+           * const result = detectLanguage("Hello world");
+           * // 返回: { language: 'en', languageName: 'English', probability: 1 }
+           * ```
+           */
+          declare function detectLanguage(text: string): LanguageDetectionResultsEntry;
+
+          export declare namespace filter {
+              export {
+                  StreamFilter
+              }
+          }
+
+          /**
+           * 将秒数转换为 xx:xx:xx.xxx 格式
+           *
+           * @export
+           * @param {number} seconds
+           * @return {*}  {string}
+           */
+          declare function formatTime(seconds: number): string;
+
+          export declare type LanguageCode = "auto" | "none" | "zh" | "zh_cn" | "zh_tw" | "yue" | "en" | "ja" | "ko" | "fr" | "es" | "ru" | "de" | "it" | "tr" | "pt" | "vi" | "id" | "th" | "ms" | "ar" | "hi" | "ro" | "ug" | "uz" | "kk" | "az" | "ky" | "fa" | "tg";
+
+          /**
+           * 将语言代码转换为名称
+           *
+           * @export
+           * @param {LanguageCode} languageCode
+           * @return {*}
+           */
+          declare function languageCodeToName(languageCode: LanguageCode): string;
+
+          /**
+           * 语言检测结果条目接口
+           * 包含检测到的语言信息
+           */
+          declare interface LanguageDetectionResultsEntry {
+              /** 语言代码 (如 'zh', 'en', 'ja' 等) */
+              language: LanguageCode;
+              /** 语言名称 (如 '中文', 'English', '日本語' 等) */
+              languageName: string;
+              /** 检测准确度概率 (0-1 之间的数值) */
+              probability: number;
+          }
+
+          declare interface OpenAIResult {
+              task: string;
+              language: string;
+              text: string;
+              words: {
+                  word: string;
+                  start: number;
+                  end: number;
+              }[];
+              segments: {
+                  text: string;
+                  start: number;
+                  end: number;
+              }[];
+          }
+
+          declare function openaiToAimSegments(json: OpenAIResult): Promise<AimSegments[]>;
+
+          export declare interface OptimizationOptions {
+              emt: boolean;
+              ep: boolean;
+              zf: boolean;
+              punc: boolean;
+              em: boolean;
+              space: boolean;
+              repeat: boolean;
+          }
+
+          /**
+           * 为数字前方自动补0到特定的位数，默认两位
+           */
+          declare function padNumber(num: number, length?: number): string;
+
+          /**
+           * Callback passed as the `onParse` callback to a parser
+           *
+           * @public
+           */
+          declare type ParseCallback<T> = (event: ParsedEvent<T>) => void;
+
+          declare interface ParsedEvent<T> {
+              type: "event";
+              event: "start" | "message" | "end";
+              data?: T;
+          }
+
+          /**
+           * Parser parser instance.
+           *
+           * Needs to be reset between reconnections/when switching data source, using the `reset()` method.
+           *
+           * @public
+           */
+          declare interface Parser<T = string> {
+              /**
+               * Feeds the parser another chunk. The method _does not_ return a parsed message.
+               * Instead, if the chunk was a complete message (or completed a previously incomplete message),
+               * it will invoke the `onParse` callback used to create the parsers.
+               *
+               * @param chunk - The chunk to parse. Can be a partial, eg in the case of streaming messages.
+               * @public
+               */
+              feed(chunk: T): void;
+              /**
+               * Resets the parser state. This is required when you have a new stream of messages -
+               * for instance in the case of a client being disconnected and reconnecting.
+               *
+               * @public
+               */
+              reset(): void;
+              end(): void;
+          }
+
+          export declare namespace parser {
+              export {
+                  srtToAimSegments,
+                  vttToAimSegments,
+                  assToAimSegments,
+                  tingwuToAimSegments,
+                  openaiToAimSegments,
+                  create as createWhisperStreamParser,
+                  create_2 as createTranslateStreamParser,
+                  create_3 as createSegmentStreamParser
+              }
+          }
+
+          /**
+           * `ParserOptions` 是一个泛型类型，用于配置解析器的回调函数。
+           *
+           * @template S - 解析开始时的状态类型
+           * @template P - 解析过程中使用的状态类型
+           * @template E - 解析结束时的状态类型
+           *
+           * @property {ParseCallback<S>} [onStart] - 解析开始时的回调函数
+           * @property {ParseCallback<P>} [onParse] - 解析过程中调用的回调函数
+           * @property {ParseCallback<P>} [onProgress] - 解析进度更新时的回调函数
+           * @property {ParseCallback<E>} [onEnd] - 解析结束时的回调函数
+           */
+          declare type ParserOptions<S, P, E> = {
+              onStart?: ParseCallback<S>;
+              onParse?: ParseCallback<P>;
+              onProgress?: ParseCallback<P>;
+              onEnd?: ParseCallback<E>;
+          };
+
+          export declare type PartialByKey<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+          /**
+           * 重复内容检测器
+           *
+           * 用于检测字幕中连续重复的内容片段，当重复次数达到阈值时会触发回调
+           */
+          declare class RepeatCheck {
+              /** 重复检测阈值，默认为2次 */
+              threshold: number;
+              /** 当前重复次数 */
+              hit: number;
+              /** 前一个字幕片段 */
+              prevSegment?: AimSegments;
+              /** 当前重复的字幕片段 */
+              hitSegment?: AimSegments;
+              /** 重复片段列表 */
+              hitSegmentList: AimSegments[];
+              /** 配置选项 */
+              options: RepeatCheckOption;
+              /**
+               * 构造函数
+               * @param options 重复检测选项
+               */
+              constructor(options?: RepeatCheckOption);
+              /**
+               * 添加字幕片段进行重复检测
+               * @param segment 要检测的字幕片段
+               */
+              push(segment: AimSegments): void;
+              /**
+               * 结束检测，处理最后的重复片段
+               */
+              end(): void;
+              /**
+               * 重置检测器状态
+               */
+              reset(): void;
+          }
+
+          /**
+           * 重复检测选项接口
+           */
+          declare interface RepeatCheckOption {
+              /** 当检测到重复内容时的回调函数 */
+              onHit?: (segment: AimSegments[]) => void;
+          }
+
+          export declare type RequiredByKey<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+
+          export declare type Segment = {
+              start: number;
+              end: number;
+          };
+
+          declare function splitToSentences(text: string, languageCode?: LanguageCode): string[];
+
+          declare function srtToAimSegments(text: string): Promise<AimSegments[]>;
+
+          declare class StreamFilter {
+              chains: Record<string, any>;
+              delimit: string;
+              onFilter?: (text: string) => any;
+              checked: boolean;
+              checkedText: string;
+              checkedLevel?: Record<string, any>;
+              filteredText: string;
+              constructor(onFilter?: (text: string) => any);
+              add(keyword: string, replaceText?: string): void;
+              parse(data: [string, string][]): void;
+              reParse(data: string[][]): void;
+              feed(c: string): void;
+              feedAll(text: string): string;
+              end(): string;
+          }
+
+          /**
+           * 字幕优化函数
+           *
+           * 对字幕片段进行全面的质量检查和优化，包括：
+           * - 重复内容检测和移除
+           * - 空白字幕处理
+           * - 0帧字幕处理（开始时间大于等于结束时间）
+           * - 标点符号检查
+           * - 句子结束标记检查
+           * - 多余空格处理
+           * - 结尾标点处理
+           *
+           * @export
+           * @param {AimSegments[]} segments - 需要优化的字幕片段数组
+           * @param {OptimizationOptions} [options] - 优化选项配置
+           * @return {Object} 返回优化结果，包含：
+           *   - result: 各种问题的索引统计
+           *   - repeat: 重复的片段列表
+           *   - segments: 优化后的字幕片段数组
+           */
+          declare function subtitleOptimization(segments: AimSegments[], options?: OptimizationOptions): {
+              result: {
+                  emt: number[];
+                  ep: number[];
+                  zf: number[];
+                  punc: number[];
+                  em: number[];
+                  space: number[];
+                  repeat: number[];
+              };
+              repeat: AimSegments[];
+              segments: AimSegments[];
+          };
+
+          /**
+           * 字幕优化使用的正则表达式
+           */
+          declare const subtitleOptimizationRegExp: {
+              /** 检测是否存在句子分割符号（逗号、句号、问号、感叹号等） */
+              punc: RegExp;
+              /** 检测是否存在行尾分割符号（句号、问号、感叹号等） */
+              em: RegExp;
+              /** 检测是否存在连续空白字符（行首行尾空白、多个连续空格） */
+              space: RegExp;
+              /** 检测是否存在行尾标点和可能存在的空格字符 */
+              ep: RegExp;
+          };
+
+          declare interface TingwuResult {
+              TaskId: string;
+              Transcription: {
+                  AudioInfo: {
+                      "Size": number;
+                      "Duration": number;
+                      "SampleRate": number;
+                      "Language": string;
+                  };
+                  Paragraphs: {
+                      ParagraphId: string;
+                      SpeakerId: string;
+                      Words: {
+                          "Id": number;
+                          "SentenceId": number;
+                          "Start": number;
+                          "End": number;
+                          "Text": string;
+                      }[];
+                  }[];
+              };
+          }
+
+          declare function tingwuToAimSegments(json: TingwuResult): Promise<AimSegments[]>;
+
+          export declare namespace tools {
+              export {
+                  subtitleOptimization,
+                  RepeatCheckOption,
+                  RepeatCheck,
+                  subtitleOptimizationRegExp,
+                  detectAllLanguage,
+                  detectLanguage,
+                  LanguageDetectionResultsEntry,
+                  splitToSentences
+              }
+          }
+
+          export declare namespace utils {
+              export {
+                  padNumber,
+                  formatTime,
+                  convertToSeconds,
+                  containsCJKCharacters,
+                  languageCodeToName,
+                  chunkArrayStrings,
+                  chunkSegmentStringsWithIndex,
+                  consolidateSegments
+              }
+          }
+
+          declare function vttToAimSegments(text: string): Promise<AimSegments[]>;
+
+          export { }