npm package: @reedef/subtitles-utils
Description: Parse and serialize SRT/VTT subtitles to JSON and plain text
Latest version: 1.0.2

# subtitles-utils

将 SRT / VTT 字幕解析为 JSON，并支持从 JSON 序列化为 SRT、VTT 或纯文本。

## 安装

```bash
npm install @reedef/subtitles-utils
```

## SubtitleCue 类型

所有解析和序列化方法都围绕 `SubtitleCue` 进行：

```ts
type SubtitleCue = {
  index?: number; // 可选序号
  start: number;  // 开始时间（秒）
  end: number;    // 结束时间（秒）
  text: string;   // 字幕文本
};
```

## API

- **`parseSrt(content: string): SubtitleCue[]`** — 解析 SRT 内容
- **`parseVtt(content: string): SubtitleCue[]`** — 解析 WebVTT 内容（会跳过 `WEBVTT` 头）
- **`parseSubtitle(content: string): SubtitleCue[]`** — 自动识别 SRT / VTT 并解析
- **`jsonToSrt(cues: SubtitleCue[]): string`** — 序列化为 SRT
- **`jsonToVtt(cues: SubtitleCue[]): string`** — 序列化为 VTT
- **`jsonToPlaintext(cues: SubtitleCue[]): string`** — 序列化为纯文本，格式：`时间: 文本`
- **`timeStringToSeconds(s: string): number`** — 将时间字符串解析为秒数
- **`normalizeSrtTime(s: string): string`** — 将时间字符串规范为 `00:00:00,000` 格式

---

### `parseSrt(content: string): SubtitleCue[]`

解析 SRT 字幕内容，支持非标准时间格式（如 `0:0:0,0`）。

```ts
import { parseSrt } from "@reedef/subtitles-utils";

const cues = parseSrt(`1
00:00:01,000 --> 00:00:03,500
你好世界

2
00:00:04,000 --> 00:00:06,000
第二行字幕`);

// [
//   { index: 1, start: 1, end: 3.5, text: "你好世界" },
//   { index: 2, start: 4, end: 6, text: "第二行字幕" },
// ]
```

### `parseVtt(content: string): SubtitleCue[]`

解析 WebVTT 字幕内容，自动跳过 `WEBVTT` 头部。VTT 使用 `.` 分隔毫秒。

```ts
import { parseVtt } from "@reedef/subtitles-utils";

const cues = parseVtt(`WEBVTT

1
00:00:01.000 --> 00:00:03.500
Hello world`);

// [{ index: 1, start: 1, end: 3.5, text: "Hello world" }]
```

### `parseSubtitle(content: string): SubtitleCue[]`

自动识别 SRT / VTT 格式并解析。如果内容以 `WEBVTT` 开头则按 VTT 解析，否则按 SRT 解析。

```ts
import { parseSubtitle } from "@reedef/subtitles-utils";

// 传入 SRT 或 VTT 内容均可，无需手动判断格式
const cues = parseSubtitle(subtitleContent);
```

### `jsonToSrt(cues: SubtitleCue[]): string`

将 `SubtitleCue[]` 序列化为 SRT 格式字符串。

```ts
import { jsonToSrt } from "@reedef/subtitles-utils";

const srt = jsonToSrt([
  { start: 1, end: 3.5, text: "你好世界" },
  { start: 4, end: 6, text: "第二行字幕" },
]);

// 1
// 00:00:01,000 --> 00:00:03,500
// 你好世界
//
// 2
// 00:00:04,000 --> 00:00:06,000
// 第二行字幕
```

### `jsonToVtt(cues: SubtitleCue[]): string`

将 `SubtitleCue[]` 序列化为 WebVTT 格式字符串，自动添加 `WEBVTT` 头。

```ts
import { jsonToVtt } from "@reedef/subtitles-utils";

const vtt = jsonToVtt([
  { start: 1, end: 3.5, text: "Hello world" },
]);

// WEBVTT
//
// 1
// 00:00:01.000 --> 00:00:03.500
// Hello world
```

### `jsonToPlaintext(cues: SubtitleCue[]): string`

将 `SubtitleCue[]` 序列化为纯文本，每行格式为 `开始秒数: 文本`。整数秒不带小数，否则保留两位小数。

```ts
import { jsonToPlaintext } from "@reedef/subtitles-utils";

const text = jsonToPlaintext([
  { start: 0, end: 2, text: "开场白" },
  { start: 2.5, end: 5, text: "正文内容" },
]);

// 0: 开场白
// 2.5: 正文内容
```

### `timeStringToSeconds(s: string): number`

将时间字符串解析为秒数（浮点），支持 `,` 或 `.` 分隔毫秒。

```ts
import { timeStringToSeconds } from "@reedef/subtitles-utils";

timeStringToSeconds("00:01:30,500"); // 90.5
timeStringToSeconds("00:00:05.200"); // 5.2
timeStringToSeconds("0:0:3,0");      // 3
```

### `normalizeSrtTime(s: string): string`

将任意时间字符串规范化为 SRT 标准格式 `HH:MM:SS,mmm`。

```ts
import { normalizeSrtTime } from "@reedef/subtitles-utils";

normalizeSrtTime("0:0:3,0");       // "00:00:03,000"
normalizeSrtTime("00:01:30.500");  // "00:01:30,500"
```

## 典型用法：格式转换

```ts
import { parseSubtitle, jsonToVtt } from "@reedef/subtitles-utils";

// SRT → VTT
const cues = parseSubtitle(srtContent);
const vtt = jsonToVtt(cues);
```

## 许可证

MIT