# @braccato/parsers 中文文档

规范地址：https://npmcn.com/package/%40braccato/parsers/

版本：0\.4\.1
npm 元数据更新时间：2026-11-07T15:45:51.606Z
中文译文更新时间：2026-11-08T13:15:23.034Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40braccato/parsers
原文对照：https://npmcn.com/package/%40braccato/parsers/?lang=original
项目主页：https://braccato.boidu.dev/
源码仓库：https://github.com/better-lyrics/braccato

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：35.6 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-03-10T21:19:43.718Z
- 最新版本发布：2026-11-07T15:45:51.234Z
- 近 30 天下载量：7212（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

Lyrics 格式解析器: TTML, LRC, SRT, QRC, Plain

## 安装

```sh
npm install @braccato/parsers
```

也可以使用：`pnpm add @braccato/parsers`、`yarn add @braccato/parsers`、`bun add @braccato/parsers`

## README

# @braccato/parsers (英语)

Lyrics格式解析器用于 TTML, LRC, SRT, QRC, 和纯文本, 并带有自动格式检测. 生产 `Lyric[]` 阵列 [`@braccato/core`](https://www.npmjs.com/package/@braccato/core) 使。 。 .

这个 [解析器指南](https://docs.betterlyrics.org/braccato/parsers) 显示如何解析每个更好的 Lyrics API 提供者的响应 .

## 安装

```bash
npm i @braccato/parsers
```

## 使用量

```typescript
import { detectParser } from "@braccato/parsers";

const parser = detectParser(inputText);
const lyrics = parser.parse(inputText, durationMs);
```

或者直接使用特定的解析器:

```typescript
import { TTMLParser, LRCParser, SRTParser, QRCParser, PlainParser } from "@braccato/parsers";

const lyrics = TTMLParser.parse(ttmlString);
```

## 解析器接口

所有解析器执行 :

```typescript
interface LyricParser {
  parse(input: string, duration?: number): Lyric[];
  metadata(input: string): LyricMetadata;
  detect(input: string): boolean;
}
```

`metadata` 阅读文件上对这首歌的描述,而不是其台词,即今天谁写的. `songwriters` 当文件入帐时为空 :

```typescript
const { songwriters } = detectParser(inputText).metadata(inputText); // ["Max Martin", "Savan Kotecha"]
```

| 格式 | 歌词的出处 |
| --- | --- |
| TTML 语言 | `<songwriters>` 在任何元数据容器中 `iTunesMetadata`红外线 `sourceMetadata`)和作曲家 `<composer:meta key="songwriter">` |
| LRC 数据 | `[au:]` 财务报告和审定财务报表 `[lr:]`。 。 。 . `[by:]` 制作文件的人的名字被排除在外 |
| 问题研究中心 | 信贷额度,例如: `作词:` 或者说 `Written by:`生产者、混合和其他角色被排除在外 |
| 平原特别小组 | 没什么 |

LRC 和 QRC 作为自由文本持有的名称被拆分 `/`, (中文(简体) ), `、`, (中文(简体) ), `，` 财务报告和审定财务报表 `,`。每种格式都会重复并保留文件给出的命令.

`detectParser` 按优先级顺序尝试每个格式: TTML, LRC, SRT, QRC, Plain. 同样的规则是单独输出 `detectFormat` 从无依赖的 `@braccato/parsers/format` 子路径, 返回 `"ttml" | "lrc" | "srt" | "qrc" | "plain"` 不装入 XML 解析器.

`TTMLParser.parse` 忽略它的 `duration` 参数,因为 TTML 文档在 `<body dur>`。通过 `parseTTMLContent` 而不是当文档省略它.

## 格式细节

### TTML 语言

`parseTTMLContent` 返回已解析的行以及文档是否同步并声明的语言:

```typescript
import { parseTTMLContent } from "@braccato/parsers";

const { lyrics, isWordSynced, language } = parseTTMLContent(ttmlString, {
  songDurationMs: 214000, // only used when <body> carries no dur
  instrumentalGapMs: 5000, // silence longer than this becomes an instrumental line
});
```

无论文档是否注明了期限,都插入了仪器行。 这在0.2.0中有所改变:0.1.x只插入到一个文件上,因为该文件 `<body>` 携带a `dur`,而这个套件的被重写 并没有打开它们,所以门不见了。 无文件 `dur` 当第一行的开始超过 `instrumentalGapMs` 中,和任何两行之间用以上分隔的一行。 外出是例外,因为没有说明歌曲的结局:通过 `songDurationMs` 为了得到它.

它读取了音节时间, `ttm:role="x-bg"` 背景声, `ttm:agent` (达到稳定的相声插槽) `v1`, (中文(简体) ), `v2`,以及 `v1000` 代表团体),来自任一团体的明快旗 `explicit` 或AMLL's (英语) `obscene`, (中文(简体) ), `itunes:key`,翻译和转写. 命名空间前缀,一个文档不用声明就使用这些前缀被恢复而不是拒绝,时间可能是时钟值或抵消次数,例如 `432.25s`, (中文(简体) ), `5m` 或者说 `250ms`。 。 。 .

### LRC 数据

`LRCParser.parse` 运行一套适合 Musixmatch 单词的定时器。 对于时机已经干净的来源,使用 `parseLRC`,它返回的文档完全按照:

```typescript
import { parseLRC, lrcFixers } from "@braccato/parsers";

const lyrics = parseLRC(lrcText, durationMs, {
  instrumentalGapMs: 5000, // silence longer than this becomes an instrumental line
});
lrcFixers(lyrics); // optional, mutates in place
```

仪表行遵循与TTML相同的规则. 空白的定时行,或只持有音乐笔记的行,不是一首歌词:它结束了它之前的行,它留下的寂静会成为工具行,当它运行的时间超过 `instrumentalGapMs`。 。 。 。 在增强的LRC中,一个时间戳在关闭了上个字和行后一无所有,所以它之后的沉默算不上是空白行. 门槛后第一行开始时会添加一个入门. 出道需要最后一行,通过收尾时间戳或后行空白一行来说明结束位置,因为一行平整的最后一行会跑到歌曲的结尾.

### 问题研究中心

`QRCParser.parse` 接受 `<QrcInfos>` 信封QQ音乐回归或赤裸的QRC正文. 通过歌曲元数据 `parseQRC` 以删除仅与标题或艺术家相呼应的开口行 :

```typescript
import { parseQRC } from "@braccato/parsers";

const lyrics = parseQRC(qrcXml, durationMs, { title: "Song", artist: "Artist" });
```

歌手前缀( R)`Name:` 在一行行头)成为代理,被从文字中剥去,坚持到下一行出现为止. 信用额度被取消.

见 [完整文档](https://braccato.boidu.dev/) 用于类型定义.

## 常见问题

### @braccato/parsers 是什么？

Lyrics 格式解析器: TTML, LRC, SRT, QRC, Plain

### 如何安装 @braccato/parsers？

在项目目录运行 npm install @braccato/parsers，或使用 pnpm add / yarn add / bun add。

### @braccato/parsers 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @braccato/parsers 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @braccato/parsers 可以商用吗？

@braccato/parsers 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @braccato/parsers 的下载量有多少？

根据 npm 官方下载统计，@braccato/parsers 在 2026/10/09 – 2026/11/07 这 30 天内被下载 7,212 次，日均约 240 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @braccato/parsers 还在维护吗？

最新版本 0\.4\.1 发布于 2026/11/07（今天）；至今共发布 12 个版本，其中过去 12 个月发布了 12 个；首次发布于 2026/03/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。