@aim-packages/subtitle 0.1.0 → 0.1.2

package/README.md

@@ -38,7 +38,10 @@ const optimizedSegments = tools.optimization.subtitleOptimization(segments, {
 const streamFilter = new filter.StreamFilter();
 streamFilter.add("敏感词", "***");
 const filteredText = streamFilter.feedAll("这是一个敏感词测试。");
-```
+
+// 字幕输出
+const segments = [["00:00:01,000", "00:00:03,000", "Hello world", "speaker1"]];
+const srtContent = tools.output.outputSrt({ segments1: segments });
 
 ## 📚 API 文档
 
@@ -298,6 +301,71 @@ const merged = utils.consolidateSegments(segments, {
 2. 可选择性地为每个片段添加 `padding` 时间，扩展片段的开始和结束时间
 3. 如果添加了 `padding`，会自动处理重叠的片段，将它们合并
 
+#### 颜色格式转换
+
+##### `convertHexColorToAssFormat(hexColor?: string): string`
+将十六进制颜色转换为 ASS 格式，用于字幕样式设置。
+
+```typescript
+import { utils } from '@aim-packages/subtitle';
+
+utils.convertHexColorToAssFormat("#FF0000");     // "&H0000FF00"
+utils.convertHexColorToAssFormat("#00FF00");     // "&H0000FF00"
+utils.convertHexColorToAssFormat("#0000FF");     // "&H00FF0000"
+utils.convertHexColorToAssFormat("#FF0000FF");   // "&HFF00FF00"
+utils.convertHexColorToAssFormat();              // ""
+```
+
+**参数说明：**
+- `hexColor?: string` - 十六进制颜色值，支持 7 位（#RRGGBB）和 9 位（#RRGGBBAA）格式
+
+**作用：**
+1. 将十六进制颜色转换为 ASS 格式，用于字幕样式设置
+2. 支持 7 位和 9 位十六进制颜色格式
+3. 自动处理颜色通道的顺序转换（RGB 转 BGR）
+
+##### `convertHexColorToFFmpegFormat(hexColor: string): string`
+将十六进制颜色转换为 FFmpeg 格式，用于字幕样式设置。
+
+```typescript
+import { utils } from '@aim-packages/subtitle';
+
+utils.convertHexColorToFFmpegFormat("#FF0000");     // "&H0000FF00&"
+utils.convertHexColorToFFmpegFormat("#00FF00");     // "&H0000FF00&"
+utils.convertHexColorToFFmpegFormat("#0000FF");     // "&H00FF0000&"
+utils.convertHexColorToFFmpegFormat("#FF0000FF");   // "&HFF00FF00&"
+```
+
+**参数说明：**
+- `hexColor: string` - 十六进制颜色值，支持 7 位（#RRGGBB）和 9 位（#RRGGBBAA）格式
+
+**作用：**
+1. 将十六进制颜色转换为 FFmpeg 格式，用于字幕样式设置
+2. 支持 7 位和 9 位十六进制颜色格式
+3. 自动处理颜色通道的顺序转换（RGB 转 BGR）
+
+#### 时间格式转换
+
+##### `convertTimeToAssFormat(str: string): string`
+将时间字符串转换为 ASS 字幕格式。
+
+```typescript
+import { utils } from '@aim-packages/subtitle';
+
+utils.convertTimeToAssFormat("01:30:45.123");  // "1:30:45.12"
+utils.convertTimeToAssFormat("00:05:30.050");  // "0:05:30.05"
+utils.convertTimeToAssFormat("00:00:00.999");  // "0:00:00.99"
+```
+
+**参数说明：**
+- `str: string` - 输入的时间字符串，格式为 HH:MM:SS.MMM
+
+**作用：**
+1. 将标准时间格式字符串转换为 ASS 字幕文件所需的时间格式
+2. 支持 HH:MM:SS.MMM 格式的输入
+3. 确保时间轴的准确性和兼容性
+4. 自动处理毫秒的精度转换（3位转2位）
+
 ### Parser 字幕格式解析器
 
 Parser 模块提供了多种字幕格式的解析和转换功能，支持 SRT、VTT、ASS 等常见字幕格式，以及流式解析器用于实时处理。
@@ -908,6 +976,286 @@ repeatCheck.push({ st: "00:00:05", et: "00:00:07", text: "Hello" }); // 重复
 repeatCheck.end();
 ```
 
+#### 字幕输出
+
+字幕输出模块提供了多种格式的字幕文件生成功能，支持SRT、VTT、LRC、ASS等主流字幕格式。
+
+##### `outputSrt(params: OutputTextParams): string`
+
+生成SRT格式的字幕文件。
+
+**参数:**
+- `params: OutputTextParams` - 输出参数配置
+
+**返回值:**
+- `string` - SRT格式的字幕内容
+
+**示例:**
+```typescript
+import { tools } from '@aim-packages/subtitle';
+
+const segments1 = [
+  ["00:00:01,000", "00:00:03,000", "Hello world", "speaker1"],
+  ["00:00:03,000", "00:00:05,000", "How are you?", "speaker2"]
+];
+
+const segments2 = [
+  ["00:00:01,000", "00:00:03,000", "你好世界", "speaker1"],
+  ["00:00:03,000", "00:00:05,000", "你好吗？", "speaker2"]
+];
+
+const speakerData = {
+  settings: {
+    speaker1: { spk: "speaker1", name: "张三", color: "#FF0000" },
+    speaker2: { spk: "speaker2", name: "李四", color: "#00FF00" }
+  },
+  speakers: { speaker1: 1, speaker2: 1 },
+  data: []
+};
+
+const srtContent = tools.output.outputSrt({
+  segments1,
+  segments2,
+  speakerData
+});
+
+console.log(srtContent);
+// 输出:
+// 1
+// 00:00:01,000 --> 00:00:03,000
+// 张三: Hello world
+// 你好世界
+// 
+// 2
+// 00:00:03,000 --> 00:00:05,000
+// 李四: How are you?
+// 你好吗？
+```
+
+##### `outputVtt(params: OutputTextParams): string`
+
+生成VTT格式的字幕文件。
+
+**参数:**
+- `params: OutputTextParams` - 输出参数配置
+
+**返回值:**
+- `string` - VTT格式的字幕内容
+
+**示例:**
+```typescript
+import { tools } from '@aim-packages/subtitle';
+
+const segments1 = [
+  ["00:00:01,000", "00:00:03,000", "Hello world", "speaker1"],
+  ["00:00:03,000", "00:00:05,000", "How are you?", "speaker2"]
+];
+
+const vttContent = tools.output.outputVtt({
+  segments1,
+  speakerData
+});
+
+console.log(vttContent);
+// 输出:
+// WEBVTT
+// 
+// 00:00:01.000 --> 00:00:03.000
+// 张三: Hello world
+// 
+// 00:00:03.000 --> 00:00:05.000
+// 李四: How are you?
+```
+
+##### `outputLrc(params: OutputTextParams): string`
+
+生成LRC格式的字幕文件。
+
+**参数:**
+- `params: OutputTextParams` - 输出参数配置
+
+**返回值:**
+- `string` - LRC格式的字幕内容
+
+**示例:**
+```typescript
+import { tools } from '@aim-packages/subtitle';
+
+const segments1 = [
+  ["00:00:01,000", "00:00:03,000", "Hello world", "speaker1"],
+  ["00:00:03,000", "00:00:05,000", "How are you?", "speaker2"]
+];
+
+const lrcContent = tools.output.outputLrc({
+  segments1,
+  segments2,
+  speakerData
+});
+
+console.log(lrcContent);
+// 输出:
+// [01.000]张三: Hello world
+// [01.000]你好世界
+// [03.000]李四: How are you?
+// [03.000]你好吗？
+```
+
+##### `outputAss(params: OutputTextParams): string`
+
+生成ASS格式的字幕文件，支持复杂的样式配置。
+
+**参数:**
+- `params: OutputTextParams` - 输出参数配置
+
+**返回值:**
+- `string` - ASS格式的字幕内容
+
+**示例:**
+```typescript
+import { tools } from '@aim-packages/subtitle';
+
+const segments1 = [
+  ["00:00:01,000", "00:00:03,000", "Hello world", "speaker1"],
+  ["00:00:03,000", "00:00:05,000", "How are you?", "speaker2"]
+];
+
+const segments2 = [
+  ["00:00:01,000", "00:00:03,000", "你好世界", "speaker1"],
+  ["00:00:03,000", "00:00:05,000", "你好吗？", "speaker2"]
+];
+
+const subtitleSettings = {
+  disabled: false,
+  stroke: true,
+  shadow: true,
+  background: true,
+  backgroundColor: "#000000",
+  main: {
+    color: "#FFFFFF",
+    borderColor: "#000000",
+    size: 18,
+    fontFamily: "Microsoft YaHei"
+  },
+  sub: {
+    color: "#FFFF00",
+    borderColor: "#000000",
+    size: 14,
+    fontFamily: "Microsoft YaHei"
+  },
+  position: {
+    bottom: 20,
+    left: 10
+  },
+  mode: "multiLang"
+};
+
+const assContent = tools.output.outputAss({
+  segments1,
+  segments2,
+  subtitleSettings,
+  speakerData,
+  isMac: false,
+  reverse: false
+});
+
+console.log(assContent);
+// 输出完整的ASS格式字幕文件，包含样式定义和字幕内容
+```
+
+##### `outputTxt(params: OutputTextParams): string`
+
+生成TXT格式的纯文本文件，支持多种输出模式。
+
+**参数:**
+- `params: OutputTextParams` - 输出参数配置
+  - `useIndex?: boolean` - 是否显示索引编号
+  - `useTimestamp?: boolean` - 是否显示时间戳
+  - `useParagraph?: boolean` - 是否使用段落模式（按发言人分组或按chunkSize分组）
+
+**返回值:**
+- `string` - TXT格式的文本内容
+
+**功能特性:**
+- **段落模式**: 支持按说话人分组或按固定大小分块
+- **行模式**: 每个字幕片段单独一行
+- **多语言支持**: 自动检测中日韩语言，调整文本连接方式
+- **说话人支持**: 支持显示说话人名称和时间戳
+
+**示例:**
+```typescript
+import { tools } from '@aim-packages/subtitle';
+
+const segments1 = [
+  ["00:00:01,000", "00:00:03,000", "Hello world", "speaker1"],
+  ["00:00:03,000", "00:00:05,000", "How are you?", "speaker1"],
+  ["00:00:05,000", "00:00:07,000", "I'm fine, thank you.", "speaker2"]
+];
+
+const segments2 = [
+  ["00:00:01,000", "00:00:03,000", "你好世界", "speaker1"],
+  ["00:00:03,000", "00:00:05,000", "你好吗？", "speaker1"],
+  ["00:00:05,000", "00:00:07,000", "我很好，谢谢。", "speaker2"]
+];
+
+const speakerData = {
+  settings: {
+    speaker1: { spk: "speaker1", name: "张三", color: "#FF0000" },
+    speaker2: { spk: "speaker2", name: "李四", color: "#00FF00" }
+  },
+  speakers: { speaker1: 1, speaker2: 1 },
+  data: []
+};
+
+// 行模式 - 每个字幕片段单独一行
+const txtContent1 = tools.output.outputTxt({
+  segments1,
+  segments2,
+  speakerData,
+  useIndex: true,
+  useTimestamp: true,
+  useParagraph: false
+});
+
+console.log(txtContent1);
+// 输出:
+// 0
+// 00:00:01,000 --> 00:00:03,000
+// 张三: Hello world
+// 你好世界
+// 
+// 1
+// 00:00:03,000 --> 00:00:05,000
+// 张三: How are you?
+// 你好吗？
+// 
+// 2
+// 00:00:05,000 --> 00:00:07,000
+// 李四: I'm fine, thank you.
+// 我很好，谢谢。
+
+// 段落模式 - 按说话人分组
+const txtContent2 = tools.output.outputTxt({
+  segments1,
+  segments2,
+  speakerData,
+  useIndex: true,
+  useTimestamp: true,
+  useParagraph: true
+});
+
+console.log(txtContent2);
+// 输出:
+// 1
+// 张三 - 00:00:01,000 --> 00:00:05,000
+// Hello world How are you?
+// 你好世界 你好吗？
+// 
+// 2
+// 李四 - 00:00:05,000 --> 00:00:07,000
+// I'm fine, thank you.
+// 我很好，谢谢。
+```
+
 #### 完整的字幕处理流程示例
 
 ```typescript
@@ -1011,6 +1359,92 @@ interface RepeatCheckOption {
 }
 ```
 
+##### `OutputTextParams`
+```typescript
+interface OutputTextParams {
+  /** 主要字幕片段数组 */
+  segments1: Array<ISegment>;
+  /** 次要字幕片段数组（如翻译字幕） */
+  segments2?: Array<ISegment>;
+  /** 字幕样式设置 */
+  subtitleSettings?: SubtitleSettings;
+  /** 说话人数据 */
+  speakerData?: SpeakerData | null;
+  /** 本地化配置 */
+  locale?: Record<string, any>;
+  
+  // TXT格式相关
+  /** 是否使用索引 */
+  useIndex?: boolean;
+  /** 是否使用时间戳 */
+  useTimestamp?: boolean;
+  /** 是否使用段落格式 */
+  useParagraph?: boolean;
+  
+  // Markdown格式相关
+  /** 文档标题 */
+  header?: string;
+  /** 是否为Markdown格式 */
+  isMd?: boolean;
+  /** 分块大小 */
+  chunkSize?: number;
+  
+  // ASS格式相关
+  /** 是否为Mac系统 */
+  isMac?: boolean;
+  /** 是否反转字幕顺序 */
+  reverse?: boolean;
+}
+```
+
+##### `ISegment`
+```typescript
+type ISegment = [string, string, string, string | undefined]
+// [开始时间, 结束时间, 文本内容, 说话人标识]
+```
+
+##### `SpeakerData`
+```typescript
+interface SpeakerData {
+  /** 说话人设置配置 */
+  settings: Record<string, { spk: string; name?: string; color: string }>;
+  /** 说话人统计 */
+  speakers: Record<string, number>;
+  /** 说话人时间数据 */
+  data: { start: number; end: number; speaker: string }[];
+  /** 其他选项 */
+  options?: { speakerCount?: number; }
+}
+```
+
+##### `SubtitleSettings`
+```typescript
+interface SubtitleSettings {
+  /** 是否禁用字幕 */
+  disabled: boolean;
+  /** 是否启用描边 */
+  stroke: boolean;
+  /** 是否启用阴影 */
+  shadow: boolean;
+  /** 是否启用背景 */
+  background: boolean;
+  /** 背景颜色 */
+  backgroundColor: string;
+  /** 主要字幕样式 */
+  main: SubtitleTextStyle;
+  /** 次要字幕样式 */
+  sub: SubtitleTextStyle;
+  /** 字幕位置 */
+  position: SubtitlePosition;
+  /** 字幕语言模式 */
+  mode: SubtitleLanguage;
+  /** 字幕顺序 */
+  order?: number[];
+  /** 水印样式 */
+  watermark?: WatermarkStyle;
+}
+```
+
 ## 🏗️ 项目结构
 
 ```
@@ -1026,10 +1460,11 @@ src/
 ## 📋 模块功能概览
 
 ### Utils 模块
-- **时间处理**: 时间格式化、秒数转换、数字补零等
+- **时间处理**: 时间格式化、秒数转换、数字补零、ASS 时间格式转换等
 - **语言处理**: 中日韩字符检测、语言代码转换等
 - **文本分块**: 按字符限制分块、字幕片段分块等
 - **字幕合并**: 合并相邻字幕片段、时间轴优化等
+- **颜色转换**: 十六进制颜色转 ASS 格式、FFmpeg 格式等
 
 ### Parser 模块
 - **格式转换**: SRT、VTT、ASS 格式之间的相互转换
@@ -1040,6 +1475,7 @@ src/
 - **语言检测**: 多语言文本的语言识别和概率分析
 - **文本分割**: 按句子、段落等规则分割文本
 - **字幕优化**: 重复检测、空白处理、质量优化等
+- **字幕输出**: 支持SRT、VTT、LRC、ASS等多种格式的字幕文件生成
 
 ### Filter 模块
 - **流式过滤**: 基于 DFA 算法的实时文本过滤