subtitles-utils

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

安装

npm install @reedef/subtitles-utils

SubtitleCue 类型

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

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）。

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 使用 . 分隔毫秒。

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 解析。

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

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

jsonToSrt(cues: SubtitleCue[]): string

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

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 头。

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[] 序列化为纯文本，每行格式为 开始秒数: 文本。整数秒不带小数，否则保留两位小数。

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

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

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。

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

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

典型用法：格式转换

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

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

许可证

MIT