API Functions

解析 / 生成 / 解密

解析函数

parse_auto

pub fn parse_auto(input: &str) -> Option<LyricsData>

自动识别输入歌词的格式并完成解析。实现在 lyrics-parsers 的 parsers::parse_lyrics_auto。

返回 None 的两种情况：

1. 无法匹配任何已知格式（LyricsRawTypes::Unknown）。
2. 输入为外层传输信封（QrcFull、YrcFull、AppleJson）。外层信封需要调用方先取出内嵌歌词文本再传入。

use lyrics_helper::parse_auto;

let content = "[00:12.00]Hello World\n[00:15.50]Second line";
let data = parse_auto(content).expect("解析失败");
assert_eq!(data.lines.as_ref().unwrap().len(), 2);

parse

pub fn parse(input: &str, raw_type: LyricsRawTypes) -> Option<LyricsData>

按指定的 LyricsRawTypes 解析歌词。已知格式时使用可避免类型检测开销。

返回 None 的情况严格限定为以下三类：

• 传入 LyricsRawTypes::Unknown；
• 传入信封格式 QrcFull、YrcFull 或 AppleJson；
• 格式为 Spotify 或 Musixmatch 时，输入文本不是符合结构的 JSON。

对于其余 7 种文本格式（Lrc、Qrc、Krc、Yrc、Ttml、LyricifySyllable、LyricifyLines），只要输入非信封，函数始终返回 Some(LyricsData)。若文本中没有任何合法歌词行，得到的将是 lines 为空列表的结构体，而非 None。

parser_for

pub fn parser_for(raw_type: LyricsRawTypes) -> Option<&'static dyn LyricsParser>

获取指定格式对应的解析器单例。parse(input, raw_type) 内部即通过 parser_for(raw_type)?.parse(input) 分发。

• Unknown 与三个信封格式没有独立解析器，返回 None。
• 各格式解析器类型（如 LrcParser、QrcParser 等）定义在 lyrics_helper::parsers::parsers，直接使用其实例需引入 use lyrics_helper::traits::LyricsParser;。

生成函数

generate_string

pub fn generate_string(lyrics_data: &LyricsData, lyrics_type: LyricsTypes) -> Option<String>

将 LyricsData 序列化为目标格式的字符串。

返回 None 的情况：

• 目标格式不支持生成（Ttml、Spotify、Musixmatch、Unknown 仅作为来源标记，无生成器）。
• 生成结果为空字符串（例如：将只有行级时间戳的 LRC 数据转为 QRC、KRC、YRC 或 Lyricify Syllable 逐字格式时，因没有音节数据而输出为空）。

use lyrics_helper::{generate_string, parse, LyricsRawTypes, LyricsTypes};

let data = parse("[0,2000]Hel(0,500)lo(500,500) World(1000,1000)", LyricsRawTypes::Qrc).unwrap();
let qrc = generate_string(&data, LyricsTypes::Qrc).unwrap();
assert!(qrc.contains("Hel(0,500)lo(500,500)"));

// 无音节数据的行级歌词无法生成逐字格式
let lrc = parse("[00:12.00]Hello World", LyricsRawTypes::Lrc).unwrap();
assert!(generate_string(&lrc, LyricsTypes::Qrc).is_none());

generator_for

pub fn generator_for(lyrics_type: LyricsTypes) -> Option<&'static dyn LyricsGenerator>

获取指定格式对应的生成器单例。支持的生成格式包括：Lrc、Qrc、Krc、Yrc、LyricifySyllable、LyricifyLines。

解密函数

decrypt_qrc 与 decrypt_krc

pub fn decrypt_qrc(encrypted: &str) -> Option<String>
pub fn decrypt_krc(encrypted: &str) -> Option<String>

• decrypt_qrc：接收十六进制密文，执行 3DES-EDE 解密与 zlib 解压。空白字符自动忽略。
• decrypt_krc：接收 Base64 字符串（完整 KRC 文件），跳过 4 字节 krc1 魔数头、循环异或解密、zlib 解压并剥离 UTF-8 BOM。

解密过程任意环节失败均返回 None。

QrcDecrypter 与 KrcDecrypter

实现 LyricsDecrypter trait 的具体解密器，通过返回 Result<String, DecryptError> 报告明确失败原因：

use lyrics_helper::traits::{DecryptError, LyricsDecrypter};
use lyrics_helper::QrcDecrypter;

match QrcDecrypter.decrypt("invalid_hex") {
    Ok(text) => println!("{text}"),
    Err(DecryptError::InvalidInput) => eprintln!("输入不是合法十六进制/Base64 或长度不足"),
    Err(DecryptError::DecompressionFailed) => eprintln!("zlib 解压缩失败"),
    Err(DecryptError::InvalidEncoding) => eprintln!("解压结果非有效 UTF-8"),
    Err(err) => eprintln!("解密失败: {err}"),
}