@applemusic-like-lyrics/lyric 1.0.2 → 1.1.0

package/dist/amll-lyric.d.mts

@@ -1,7 +1,7 @@
 //#region src/types.d.ts
 /**
-* 一个歌词单词
-*/
+ * 一个歌词单词
+ */
 interface LyricWord {
   /** 单词的起始时间 */
   startTime: number;
@@ -13,215 +13,362 @@ interface LyricWord {
   romanWord?: string;
 }
 /**
-* 一行歌词，存储多个单词
-* 如果是 LyRiC 等只能表达一行歌词的格式，则会将整行当做一个单词存储起来
-*/
+ * 一行歌词，存储多个单词
+ * 如果是 LyRiC 等只能表达一行歌词的格式，则会将整行当做一个单词存储起来
+ */
 interface LyricLine {
   /**
-  * 该行的所有单词
-  * 如果是 LyRiC 等只能表达一行歌词的格式，这里就只会有一个单词
-  */
+   * 该行的所有单词
+   * 如果是 LyRiC 等只能表达一行歌词的格式，这里就只会有一个单词
+   */
   words: LyricWord[];
   /**
-  * 该行的翻译
-  */
+   * 该行的翻译
+   */
   translatedLyric: string;
   /**
-  * 该行的音译
-  */
+   * 该行的音译
+   */
   romanLyric: string;
   /**
-  * 该行是否为背景歌词行
-  * 此选项只有作为 Lyricify Syllable 文件格式导入导出时才有意义
-  */
+   * 该行是否为背景歌词行
+   * 此选项只有作为 Lyricify Syllable 文件格式导入导出时才有意义
+   */
   isBG: boolean;
   /**
-  * 该行是否为对唱歌词行（即歌词行靠右对齐）
-  * 此选项只有作为 Lyricify Syllable 文件格式导入导出时才有意义
-  */
+   * 该行是否为对唱歌词行（即歌词行靠右对齐）
+   * 此选项只有作为 Lyricify Syllable 文件格式导入导出时才有意义
+   */
   isDuet: boolean;
   /**
-  * 该行的开始时间
-  *
-  * **并不总是等于第一个单词的开始时间**
-  */
+   * 该行的开始时间
+   *
+   * **并不总是等于第一个单词的开始时间**
+   */
   startTime: number;
   /**
-  * 该行的结束时间
-  *
-  * **并不总是等于最后一个单词的开始时间**
-  */
+   * 该行的结束时间
+   *
+   * **并不总是等于最后一个单词的开始时间**
+   */
   endTime: number;
 }
 /**
-* 一个 TTML 歌词行对象，存储了歌词行信息和 AMLL 元数据信息
-*/
+ * 一段带元数据的歌词，元数据以 `[键, 值数组]` 的形式存储
+ *
+ * 与 {@link TTMLLyric} 结构相同，用于描述不限于 TTML 的歌词对象
+ */
+type LyricParseResult = TTMLLyric;
+/**
+ * 一个 TTML 歌词行对象，存储了歌词行信息和 AMLL 元数据信息
+ */
 interface TTMLLyric {
   /**
-  * TTML 中存储的歌词行信息
-  */
+   * TTML 中存储的歌词行信息
+   */
   lines: LyricLine[];
   /**
-  * 一个元数据表，以 `[键, 值数组]` 的形式存储
-  */
+   * 一个元数据表，以 `[键, 值数组]` 的形式存储
+   */
   metadata: [string, string[]][];
 }
 //#endregion
 //#region src/formats/ass.d.ts
 /**
-* 将歌词数组转换为 ASS 字幕格式字符串
-* @param lines 歌词数组
-* @returns ASS 字幕格式字符串
-*/
+ * 将歌词数组转换为 ASS 字幕格式字符串
+ * @param lines 歌词数组
+ * @returns ASS 字幕格式字符串
+ */
 declare function stringifyAss(lines: LyricLine[]): string;
 //#endregion
 //#region src/formats/eqrc/index.d.ts
 /**
-* 解密十六进制字符串格式的 Qrc 歌词数据
-* 解密后可去头尾 XML 数据后通过调用 `parseQrc` 解析歌词行
-* @param encryptedHexString 十六进制格式的字符串，代表被加密的歌词数据
-* @returns 被解密出来的歌词字符串，是前后有 XML 混合的 QRC 歌词
-*/
+ * 解密十六进制字符串格式的 Qrc 歌词数据
+ * 解密后可去头尾 XML 数据后通过调用 `parseQrc` 解析歌词行
+ * @param encryptedHexString 十六进制格式的字符串，代表被加密的歌词数据
+ * @returns 被解密出来的歌词字符串，是前后有 XML 混合的 QRC 歌词
+ */
 declare function decryptQrcHex(encryptedHexString: string): string;
 /**
-* 对明文执行加密操作。
-* @param plaintext 明文字符串
-* @returns 十六进制格式的字符串，代表被加密的歌词数据
-*/
+ * 对明文执行加密操作。
+ * @param plaintext 明文字符串
+ * @returns 十六进制格式的字符串，代表被加密的歌词数据
+ */
 declare function encryptQrcHex(plaintext: string): string;
 //#endregion
-//#region src/formats/eslrc.d.ts
-/**
-* 解析 ESLyric 逐词歌词格式字符串
-* @param eslrc 歌词字符串
-* @returns 成功解析出来的歌词
-*/
-declare function parseEslrc(eslrc: string): LyricLine[];
-/**
-* 将歌词数组转换为 ESLyric 逐词歌词格式字符串
-* @param lines 歌词数组
-* @returns ESLyric 逐词歌词格式字符串
-*/
-declare function stringifyEslrc(lines: LyricLine[]): string;
-//#endregion
 //#region src/formats/lqe.d.ts
 /**
-* 解析 LQE 格式的歌词字符串
-* @param lqe 歌词字符串
-* @returns 成功解析出来的歌词
-*/
+ * 解析 LQE 格式的歌词字符串
+ * @param lqe 歌词字符串
+ * @returns 成功解析出来的歌词
+ */
 declare function parseLqe(lqe: string): LyricLine[];
 /**
-* 将歌词数组转换为 LQE 格式的字符串
-* @param lines 歌词数组
-* @returns LQE 格式的字符串
-*/
+ * 将歌词数组转换为 LQE 格式的字符串
+ * @param lines 歌词数组
+ * @returns LQE 格式的字符串
+ */
 declare function stringifyLqe(lines: LyricLine[]): string;
 //#endregion
-//#region src/formats/lrc.d.ts
+//#region src/formats/lrc/types.d.ts
 /**
-* 解析 LyRiC 格式的歌词字符串
-* @param lrc 歌词字符串
-* @returns 成功解析出来的歌词
-*/
-declare function parseLrc(lrc: string): LyricLine[];
+ * 歌词模式
+ * - `"plain"`: 普通 LRC，不含逐字信息
+ * - `"enhanced"`: 增强型 LRC
+ * - `"spl"`: Salt Player Lyrics，为前两者的超集
+ */
+type LrcMode = "plain" | "enhanced" | "spl";
+//#endregion
+//#region src/formats/lrc/generator.d.ts
 /**
-* 将歌词数组转换为 LyRiC 格式的字符串
-* @param lines 歌词数组
-* @returns LyRiC 格式的字符串
-*/
-declare function stringifyLrc(lines: LyricLine[]): string;
+ * 普通 LRC 显式结束时间戳的输出配置
+ *
+ * 逐字歌词的结束时间戳由最后一个音节携带，不受此配置影响
+ */
+interface LrcEndTimestampOptions {
+  /**
+   * 输出策略
+   * - `"none"`: 不输出
+   * - `"always"`: 总是输出
+   * - `"interval"`: 与下一行的间隔不小于 `intervalGap` 时输出
+   * @default "none"
+   */
+  mode?: "none" | "always" | "interval";
+  /**
+   * 触发间隔，单位毫秒，仅在 `mode` 为 `"interval"` 时有效
+   * @default 5000
+   */
+  intervalGap?: number;
+}
+/**
+ * 单种辅助行（翻译、音译或背景人声）的输出配置
+ */
+interface LrcAuxiliaryLineOptions {
+  /**
+   * 是否输出该辅助行
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * 是否内联到主歌词行，仅在普通 LRC 模式下有效
+   *
+   * translation、romanization 与 backgroundVocal 中最多只有一个可以内联
+   *
+   * 内联时辅助文本会以半角圆括号 `(text)` 包裹
+   */
+  inline?: boolean;
+}
+/**
+ * 辅助行的输出配置
+ */
+interface LrcAuxiliaryLinesOptions {
+  /**
+   * 辅助行的输出顺序
+   * @default "translation-first"
+   */
+  order?: "translation-first" | "romanization-first";
+  /**
+   * 翻译行设置
+   */
+  translation?: LrcAuxiliaryLineOptions;
+  /**
+   * 音译行设置
+   */
+  romanization?: LrcAuxiliaryLineOptions;
+  /**
+   * 背景人声设置
+   */
+  backgroundVocal?: LrcAuxiliaryLineOptions;
+}
+/**
+ * 生成 LRC 家族歌词的配置
+ */
+interface StringifyLrcLikeOptions {
+  /**
+   * 生成模式，详见 {@link LrcMode}
+   * @default "plain"
+   */
+  mode?: LrcMode;
+  /**
+   * 逐字时间戳的括号类型，仅在 `enhanced` 和 `spl` 模式下有效
+   * - `"angle"`: 使用 `<mm:ss.ms>`
+   * - `"square"`: 使用 `[mm:ss.ms]`
+   * @default "angle"
+   */
+  inlineBracket?: "angle" | "square";
+  /**
+   * 辅助行（翻译、音译、背景人声）的输出配置
+   */
+  auxiliaryLines?: LrcAuxiliaryLinesOptions;
+  /**
+   * 普通 LRC 的显式结束时间戳输出配置
+   */
+  endTimestamp?: LrcEndTimestampOptions;
+}
 //#endregion
-//#region src/formats/lrca2.d.ts
+//#region src/formats/lrc/parser.d.ts
+interface ParseLrcLikeOptions {
+  /**
+   * 解析模式，详见 {@link LrcMode}
+   * @default "spl"
+   */
+  mode?: LrcMode;
+}
+//#endregion
+//#region src/formats/lrc/index.d.ts
+/**
+ * 解析任意 LRC 家族歌词，包括普通 LRC、增强型 LRC、ESLyric 逐词歌词与 Salt Player Lyrics
+ *
+ * 因为 Salt Player Lyrics 是其余格式的超集，所以一个接口即可解析全部种类
+ *
+ * 同一时间可能出现多条歌词行（例如翻译与音译），
+ * 本接口不做多语言适配，由使用者自行决定如何使用这些时间相同的歌词行
+ *
+ * @param text 歌词文本
+ * @param options 解析选项
+ * @returns 解析出来的歌词与元数据
+ */
+declare function parseLrcLike(text: string, options?: ParseLrcLikeOptions): LyricParseResult;
+/**
+ * 生成 LRC 家族歌词
+ * @param input 歌词行，或带元数据的解析结果
+ * @param options 生成选项
+ * @returns 歌词文本
+ */
+declare function stringifyLrcLike(input: LyricParseResult | LyricLine[], options?: StringifyLrcLikeOptions): string;
 /**
-* 解析 LRC A2 格式的歌词字符串
-* @param lrc 歌词字符串
-* @returns 成功解析出来的歌词
-*/
+ * 解析 LyRiC 格式的歌词字符串
+ * @param lrc 歌词字符串
+ * @returns 成功解析出来的歌词
+ */
+declare function parseLrc(lrc: string): LyricLine[];
+/**
+ * 解析 ESLyric 逐词歌词格式的歌词字符串
+ * @param eslrc 歌词字符串
+ * @returns 成功解析出来的歌词
+ */
+declare function parseEslrc(eslrc: string): LyricLine[];
+/**
+ * 解析 LRC A2（增强 LRC）格式的歌词字符串
+ * @param lrc 歌词字符串
+ * @returns 成功解析出来的歌词
+ */
 declare function parseLrcA2(lrc: string): LyricLine[];
 /**
-* 将歌词数组转换为 LRC A2 格式的字符串
-* @param lines 歌词数组
-* @returns LRC A2 格式的字符串
-*/
+ * 解析 SPL（Salt Player Lyrics）格式的歌词字符串
+ *
+ * 上述几种格式都语出同源，本接口只是以 SPL 之名调用同一套解析算法
+ * @param spl 歌词字符串
+ * @returns 成功解析出来的歌词
+ */
+declare function parseSPL(spl: string): LyricLine[];
+/**
+ * 将歌词数组转换为 LyRiC 格式的字符串
+ * @param lines 歌词数组
+ * @returns LyRiC 格式的字符串
+ */
+declare function stringifyLrc(lines: LyricLine[]): string;
+/**
+ * 将歌词数组转换为 ESLyric 逐词歌词格式的字符串
+ *
+ * ESLyric 的逐词语法为「文本后跟该词的结束时间」，行首时间戳即首个词的开始时间，
+ * 因此不写行自身的时间戳，行首时间戳直接取首个词的开始时间
+ * @param lines 歌词数组
+ * @returns ESLyric 逐词歌词格式的字符串
+ */
+declare function stringifyEslrc(lines: LyricLine[]): string;
+/**
+ * 将歌词数组转换为 LRC A2（增强 LRC）格式的字符串
+ * @param lines 歌词数组
+ * @returns LRC A2 格式的字符串
+ */
 declare function stringifyLrcA2(lines: LyricLine[]): string;
+/**
+ * 生成 SPL（Salt Player Lyrics）格式的歌词字符串
+ *
+ * SPL 与增强型 LRC 的生成行为一致，逐字时间戳同样使用尖括号，
+ * 因此本接口与 {@link stringifyLrcA2} 的输出完全相同
+ * @param input 歌词行，或带元数据的解析结果
+ * @returns SPL 格式的字符串
+ */
+declare function stringifySPL(input: LyricParseResult | LyricLine[]): string;
 //#endregion
 //#region src/formats/lyl.d.ts
 /**
-* 解析 LYL 格式的歌词字符串
-* @param lyl 歌词字符串
-* @returns 成功解析出来的歌词
-*/
+ * 解析 LYL 格式的歌词字符串
+ * @param lyl 歌词字符串
+ * @returns 成功解析出来的歌词
+ */
 declare function parseLyl(lyl: string): LyricLine[];
 /**
-* 将歌词数组转换为 LYL 格式的字符串
-* @param lines 歌词数组
-* @returns LYL 格式的字符串
-*/
+ * 将歌词数组转换为 LYL 格式的字符串
+ * @param lines 歌词数组
+ * @returns LYL 格式的字符串
+ */
 declare function stringifyLyl(lines: LyricLine[]): string;
 //#endregion
 //#region src/formats/lys.d.ts
 /**
-* 解析 LYS 格式的歌词字符串
-* @param lys 歌词字符串
-* @returns 成功解析出来的歌词
-*/
+ * 解析 LYS 格式的歌词字符串
+ * @param lys 歌词字符串
+ * @returns 成功解析出来的歌词
+ */
 declare function parseLys(lys: string): LyricLine[];
 /**
-* 将歌词数组转换为 LYS 格式的字符串
-* @param lines 歌词数组
-* @returns LYS 格式的字符串
-*/
+ * 将歌词数组转换为 LYS 格式的字符串
+ * @param lines 歌词数组
+ * @returns LYS 格式的字符串
+ */
 declare function stringifyLys(lines: LyricLine[]): string;
 //#endregion
 //#region src/formats/qrc.d.ts
 /**
-* 解析 QRC 格式的歌词字符串
-* @param qrc 歌词字符串
-* @returns 成功解析出来的歌词
-*/
+ * 解析 QRC 格式的歌词字符串
+ * @param qrc 歌词字符串
+ * @returns 成功解析出来的歌词
+ */
 declare function parseQrc(qrc: string): LyricLine[];
 /**
-* 将歌词数组转换为 QRC 格式的字符串
-* @param lines 歌词数组
-* @returns QRC 格式的字符串
-*/
+ * 将歌词数组转换为 QRC 格式的字符串
+ * @param lines 歌词数组
+ * @returns QRC 格式的字符串
+ */
 declare function stringifyQrc(lines: LyricLine[]): string;
 //#endregion
 //#region src/formats/ttml.d.ts
 /**
-* 解析 TTML 格式（包含 AMLL 特有属性信息）的歌词字符串
-* @param ttmlText 歌词字符串
-* @returns 成功解析出来的 TTML 歌词对象
-*/
+ * 解析 TTML 格式（包含 AMLL 特有属性信息）的歌词字符串
+ * @param ttmlText 歌词字符串
+ * @returns 成功解析出来的 TTML 歌词对象
+ */
 declare function parseTTML(ttmlText: string): TTMLLyric;
 /**
-* 将歌词数组转换为 TTML 格式（包含 AMLL 特有属性信息）的歌词字符串
-* @param ttmlLyric TTML 歌词对象
-*/
+ * 将歌词数组转换为 TTML 格式（包含 AMLL 特有属性信息）的歌词字符串
+ * @param ttmlLyric TTML 歌词对象
+ */
 declare function stringifyTTML(ttmlLyric: TTMLLyric): string;
 //#endregion
 //#region src/formats/yrc.d.ts
 /**
-* 解析 YRC 格式的歌词字符串
-* @param yrc 歌词字符串
-* @returns 成功解析出来的歌词
-*/
+ * 解析 YRC 格式的歌词字符串
+ * @param yrc 歌词字符串
+ * @returns 成功解析出来的歌词
+ */
 declare function parseYrc(yrc: string): LyricLine[];
 /**
-* 将歌词数组转换为 YRC 格式的字符串
-* @param lines 歌词数组
-* @returns YRC 格式的字符串
-*/
+ * 将歌词数组转换为 YRC 格式的字符串
+ * @param lines 歌词数组
+ * @returns YRC 格式的字符串
+ */
 declare function stringifyYrc(lines: LyricLine[]): string;
 //#endregion
 //#region src/index.d.ts
 /**
-* {@link stringifyLrcA2} 的别名。
-*
-* @deprecated 此为兼容旧版本拼写错误的接口，请改用 `stringifyLrcA2`。此接口将在未来版本中移除。
-*/
+ * {@link stringifyLrcA2} 的别名。
+ *
+ * @deprecated 此为兼容旧版本拼写错误的接口，请改用 `stringifyLrcA2`。此接口将在未来版本中移除。
+ */
 declare function stringifylrcA2(...args: Parameters<typeof stringifyLrcA2>): ReturnType<typeof stringifyLrcA2>;
 //#endregion
-export { type LyricLine, type LyricWord, type TTMLLyric, decryptQrcHex, encryptQrcHex, parseEslrc, parseLqe, parseLrc, parseLrcA2, parseLyl, parseLys, parseQrc, parseTTML, parseYrc, stringifyAss, stringifyEslrc, stringifyLqe, stringifyLrc, stringifyLrcA2, stringifyLyl, stringifyLys, stringifyQrc, stringifyTTML, stringifyYrc, stringifylrcA2 };
+export { type LrcAuxiliaryLineOptions, type LrcAuxiliaryLinesOptions, type LrcEndTimestampOptions, type LyricLine, type LyricParseResult, type LyricWord, type ParseLrcLikeOptions, type StringifyLrcLikeOptions, type TTMLLyric, decryptQrcHex, encryptQrcHex, parseEslrc, parseLqe, parseLrc, parseLrcA2, parseLrcLike, parseLyl, parseLys, parseQrc, parseSPL, parseTTML, parseYrc, stringifyAss, stringifyEslrc, stringifyLqe, stringifyLrc, stringifyLrcA2, stringifyLrcLike, stringifyLyl, stringifyLys, stringifyQrc, stringifySPL, stringifyTTML, stringifyYrc, stringifylrcA2 };
 //# sourceMappingURL=amll-lyric.d.mts.map