Getting Started

快速开始

安装

cargo add lyrics-helper

离线使用（不包含 lyrics-search，无网络依赖）：

cargo add lyrics-helper --no-default-features

基本用法

自动识别格式并解析

parse_auto() 会先识别文本格式，再解析为统一的 LyricsData 结构：

use lyrics_helper::parse_auto;

fn main() {
    let content = "[00:12.00]Hello World\n[00:15.50]Second line";
    let data = parse_auto(content).expect("识别或解析失败");

    if let Some(lines) = &data.lines {
        println!("共 {} 行歌词", lines.len());
        for line in lines {
            println!("[{:?}] {}", line.start_time(), line.text_from_any());
        }
    }
}

支持自动识别的格式包括：LRC、QRC、KRC、YRC、TTML、Spotify JSON、Musixmatch JSON、Lyricify Syllable、Lyricify Lines。

Note

Apple Music JSON（AppleJson）、QRC XML 信封（QrcFull）与网易云 YRC 信封（YrcFull）仅能被 get_lyrics_types() 识别，parse_auto() 对它们返回 None。必须先从外层信封提取内嵌歌词字符串，再交给 parse() 解析。

指定格式解析

已知格式时直接传入 LyricsRawTypes，跳过检测流程：

use lyrics_helper::{parse, LyricsRawTypes};

fn main() {
    let lrc = "[00:12.00]Hello World\n[00:15.50]Second line";
    let data = parse(lrc, LyricsRawTypes::Lrc).expect("解析失败");

    if let Some(meta) = &data.track_metadata {
        println!("曲名: {:?}", meta.title);
        println!("艺术家: {:?}", meta.artist);
    }

    if let Some(lines) = &data.lines {
        for line in lines {
            println!("{}", line.text_from_any());
        }
    }
}

格式转换与导出

解析出的 LyricsData 可导出为指定目标格式：

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

fn main() {
    let syllable = "[4]Hel(0,600)lo(600,400) (1000,300)World(1300,700)\n\
                    [4]Second(3000,1200) (4200,200)line(4400,1100)";
    let data = parse(syllable, LyricsRawTypes::LyricifySyllable).expect("解析失败");

    // 逐字 -> QRC
    let qrc = generate_string(&data, LyricsTypes::Qrc).expect("生成 QRC 失败");
    println!("{qrc}");

    // 逐字 -> Lyricify Syllable
    let lyricify = generate_string(&data, LyricsTypes::LyricifySyllable).expect("生成失败");
    println!("{lyricify}");

    // 逐字 -> 逐行 LRC（降级）
    let lrc = generate_string(&data, LyricsTypes::Lrc).expect("生成 LRC 失败");
    println!("{lrc}");
}

注意：QRC、KRC、YRC 和 Lyricify Syllable 生成器仅输出音节级行。若输入数据只有行级时间（如 LRC），生成这些逐字格式时会返回 None。详见 支持的格式 中的转换矩阵。

读取音节（逐字时间）

对于逐字格式（QRC、KRC、YRC、TTML 逐字、Lyricify Syllable），歌词行包含音节（SyllableItem）信息：

use lyrics_helper::models::LineInfo;
use lyrics_helper::{parse, LyricsRawTypes};

fn main() {
    let content = "[0,2000]Hello(0,600) (600,400)World(1000,1000)\n\
                   [3000,2500]Second(3000,1200) (4200,200)line(4400,1100)";
    let data = parse(content, LyricsRawTypes::Qrc).expect("解析失败");

    if let Some(lines) = &data.lines {
        for line in lines {
            match line {
                LineInfo::Syllable { syllables, .. } | LineInfo::FullSyllable { syllables, .. } => {
                    for syl in syllables {
                        println!("  [{},{}] {}", syl.start_time(), syl.end_time(), syl.text());
                    }
                }
                LineInfo::Line { text, .. } | LineInfo::FullLine { text, .. } => {
                    println!("{}", text);
                }
            }
        }
    }
}

本地命令行演示

仓库提供了一个完整的 CLI 演示程序（位于 crates/lyrics-helper/examples/demo.rs），可从 workspace 根目录直接执行：

# 演示所有解析器
cargo run --example demo -- parsers-demo

# 解析指定文件
cargo run --example demo -- parse crates/lyrics-helper/tests/test_data/LrcDemo.txt lrc

# 格式转换
cargo run --example demo -- generate crates/lyrics-helper/tests/test_data/LyricifySyllableDemo.txt lyricify-syllable qrc

# 自动格式检测
cargo run --example demo -- detect crates/lyrics-helper/tests/test_data/LrcDemo.txt

# 解密演示
cargo run --example demo -- decrypt-qrc encrypted.qrc
cargo run --example demo -- decrypt-krc encrypted.krc