Subtitle

一个功能完整的字幕文件处理工具，支持SRT和WebVTT格式的解析、转换、验证和JSON导出。

功能特点

• 🚀 轻量级，零依赖
• 📝 完整的TypeScript类型支持
• 🔧 支持多行字幕文本
• ✅ 格式验证功能（SRT和WebVTT）
• 🎯 简单易用的API
• 🔄 支持SRT和WebVTT互相转换
• 📄 支持转换为JSON格式
• 🌐 支持中英文分词（中文使用jieba-wasm，英文使用compromise）

安装

npm install @xiping/subtitle

或者使用pnpm：

pnpm add @xiping/subtitle

使用方法

基本用法

import { srtToVtt } from '@xiping/subtitle';

const srtContent = `1
00:00:00,000 --> 00:00:04,000
你好，这是第一行字幕

2
00:00:05,000 --> 00:00:09,000
这是第二行字幕`;

const webvttContent = srtToVtt(srtContent);
console.log(webvttContent);

输出结果：

WEBVTT

00:00:00.000 --> 00:00:04.000
你好，这是第一行字幕

00:00:05.000 --> 00:00:09.000
这是第二行字幕

高级用法

import { 
  srtToVtt, 
  parseSRT, 
  parseVTT,
  generateWebVTT, 
  validateSRT,
  validateVTT,
  SubtitleEntry 
} from '@xiping/subtitle';

// 验证SRT格式
const isValid = validateSRT(srtContent);
if (!isValid) {
  console.error('无效的SRT格式');
  return;
}

// 解析SRT文件
const entries: SubtitleEntry[] = parseSRT(srtContent);
console.log('字幕条目数量:', entries.length);

// 手动生成WebVTT
const webvtt = generateWebVTT(entries);

// 解析WebVTT文件
const vttContent = `WEBVTT\n\n00:00:00.000 --> 00:00:04.000\n字幕内容`;
const vttEntries = parseVTT(vttContent);

// 验证WebVTT格式
const isVttValid = validateVTT(vttContent);

JSON转换

import { srtToJson, vttToJson, SubtitleLanguage } from '@xiping/subtitle';

// SRT转JSON（中文，使用jieba-wasm分词）
const srtContent = `1
00:00:00,000 --> 00:00:04,000
中华人民共和国`;

const jsonContent = await srtToJson(srtContent, 'zh');
console.log(jsonContent);
// 输出包含分词结果: [{"index":1,"startTime":"00:00:00,000","endTime":"00:00:04,000","text":"中华人民共和国","words":["中华人民共和国",...]}]

// SRT转JSON（英文，使用compromise分词）
const englishSrt = `1
00:00:00,000 --> 00:00:04,000
Hello world, this is a test.`;

const englishJson = await srtToJson(englishSrt, 'en');
// 输出包含英文分词结果

// WebVTT转JSON
const vttContent = `WEBVTT

00:00:00.000 --> 00:00:04.000
字幕内容`;

const vttJson = await vttToJson(vttContent, 'zh');

文件操作示例

import fs from 'fs';
import { srtToVtt, srtToJson } from '@xiping/subtitle';

// 读取SRT文件
const srtContent = fs.readFileSync('subtitle.srt', 'utf-8');

// 转换为WebVTT
const webvttContent = srtToVtt(srtContent);
fs.writeFileSync('subtitle.vtt', webvttContent, 'utf-8');

// 转换为JSON（需要指定语言类型）
const jsonContent = await srtToJson(srtContent, 'zh');
fs.writeFileSync('subtitle.json', jsonContent, 'utf-8');

API 文档

srtToVtt(srtContent: string): string

主转换函数，将SRT格式字幕转换为WebVTT格式。

参数:

• srtContent - SRT格式的字幕内容

返回值:

• WebVTT格式的字幕字符串

parseSRT(srtContent: string): SubtitleEntry[]

解析SRT字幕文件内容。

参数:

• srtContent - SRT格式的字幕内容

返回值:

• 解析后的字幕条目数组

generateWebVTT(entries: SubtitleEntry[]): string

将字幕条目数组转换为WebVTT格式字符串。

参数:

• entries - 字幕条目数组

返回值:

• WebVTT格式字符串

validateSRT(srtContent: string): boolean

验证SRT文件格式是否正确。

参数:

• srtContent - SRT格式的字幕内容

返回值:

• 是否为有效的SRT格式

parseVTT(vttContent: string): SubtitleEntry[]

解析WebVTT字幕文件内容。

参数:

• vttContent - WebVTT格式的字幕内容

返回值:

• 解析后的字幕条目数组

validateVTT(vttContent: string): boolean

验证WebVTT文件格式是否正确。

参数:

• vttContent - WebVTT格式的字幕内容

返回值:

• 是否为有效的WebVTT格式

srtToJson(srtContent: string, language?: SubtitleLanguage): Promise<string>

将SRT字幕转换为JSON格式字符串，并自动进行分词处理。

参数:

• srtContent - SRT格式的字幕内容
• language - 字幕语言类型，可选值：'zh'（中文，默认）或 'en'（英文）

返回值:

• Promise，解析为JSON格式字符串（格式化，缩进2空格）
• JSON中包含 words 字段，为分词后的单词数组
  • 中文使用 jieba-wasm 进行分词
  • 英文使用 compromise 进行分词

vttToJson(vttContent: string, language?: SubtitleLanguage): Promise<string>

将WebVTT字幕转换为JSON格式字符串，并自动进行分词处理。

参数:

• vttContent - WebVTT格式的字幕内容
• language - 字幕语言类型，可选值：'zh'（中文，默认）或 'en'（英文）

返回值:

• Promise，解析为JSON格式字符串（格式化，缩进2空格）
• JSON中包含 words 字段，为分词后的单词数组
  • 中文使用 jieba-wasm 进行分词
  • 英文使用 compromise 进行分词

convertTimeFormat(srtTime: string): string

将SRT时间格式转换为WebVTT时间格式。

参数:

• srtTime - SRT时间格式 (HH:MM:SS,mmm)

返回值:

• WebVTT时间格式 (HH:MM:SS.mmm)

类型定义

// 字幕语言类型
type SubtitleLanguage = 'zh' | 'en';

interface SubtitleEntry {
  index: number;      // 字幕序号
  startTime: string;  // 开始时间
  endTime: string;    // 结束时间
  text: string;       // 字幕文本
  words?: string[];   // 分词后的单词数组（可选，仅在转换为JSON时生成）
}

格式说明

SRT格式示例

1
00:00:00,000 --> 00:00:04,000
第一行字幕

2
00:00:05,000 --> 00:00:09,000
第二行字幕
可以是多行文本

WebVTT格式示例

WEBVTT

00:00:00.000 --> 00:00:04.000
第一行字幕

00:00:05.000 --> 00:00:09.000
第二行字幕
可以是多行文本

主要差异

• 文件头: WebVTT以WEBVTT开头
• 时间分隔符: SRT使用逗号,，WebVTT使用点号.
• 序号: SRT包含序号，WebVTT不需要

错误处理

库会自动处理常见的格式错误：

import { validateSRT, srtToVtt } from '@xiping/subtitle';

const srtContent = "invalid content";

if (!validateSRT(srtContent)) {
  console.error('SRT格式无效');
} else {
  const result = srtToVtt(srtContent);
  console.log(result);
}

浏览器支持

该库支持所有现代浏览器和Node.js环境。WebVTT格式被广泛支持：

• Chrome 23+
• Firefox 31+
• Safari 6+
• Edge 12+
• iOS Safari 7+
• Android Browser 4.4+

贡献

欢迎提交Issue和Pull Request！

许可证

MIT License

相关链接

• WebVTT规范
• SRT格式说明