Migration 0.2

从 0.1 升级到 0.2

0.2.0 是破坏性版本。六个 crate 统一为 0.2.0，并且改变了逐字歌词的音节模型。

依赖写法

[dependencies]
lyrics-helper = "0.2"

仅需离线解析时禁用默认 feature：

[dependencies]
lyrics-helper = { version = "0.2", default-features = false }

音节模型：SyllableInfo -> SyllableItem

LineInfo::Syllable 与 LineInfo::FullSyllable 的 syllables 字段，由 Vec<SyllableInfo> 变为 Vec<SyllableItem>，对应上游 C# 的 ISyllableInfo。

新增的 SyllableItem::Full(FullSyllableInfo) 表示同一单词内被合并的音节，它保留各子音节各自的时间信息，聚合文本与首尾时间由子项推导。这样 Apple Music、Musixmatch 这类把一个单词拆成多个时间片段的来源，既能按单词显示，也不丢失子音节的时间。

只读取文本和时间

把字段访问换成同名方法即可：

// 0.1
let text = &syllables[0].text;
let start = syllables[0].start_time;
let end = syllables[0].end_time;

// 0.2
let text = syllables[0].text();
let start = syllables[0].start_time();
let end = syllables[0].end_time();

需要扁平的音节序列

自己生成逐字格式、或沿用原有按 SyllableInfo 逐个处理的逻辑时：

use lyrics_helper::{flatten_syllable_items, to_syllable_items, SyllableInfo};

// 逐字来源（QRC / KRC / YRC / TTML / Apple Music / Spotify 等）解析出的音节项列表
let syllables = to_syllable_items(vec![
    SyllableInfo::new("Hel".to_string(), 0, 500),
    SyllableInfo::new("lo".to_string(), 500, 1000),
]);

// Vec<SyllableItem> -> Vec<SyllableInfo>，合并音节展开为其子音节
let flat = flatten_syllable_items(&syllables);
assert_eq!(flat.len(), 2);

// 反向包装
let items = to_syllable_items(flat);
assert_eq!(items.len(), 2);

单个音节项可以用 parts() 拿到不分配的 &[SyllableInfo]：

use lyrics_helper::{get_text_from_syllable_items, to_syllable_items, SyllableInfo};

let syllables = to_syllable_items(vec![
    SyllableInfo::new("Hel".to_string(), 0, 500),
    SyllableInfo::new("lo".to_string(), 500, 1000),
]);

for item in &syllables {
    for part in item.parts() {
        println!("[{},{}] {}", part.start_time, part.end_time, part.text);
    }
}

assert_eq!(get_text_from_syllable_items(&syllables), "Hello");

构造音节行

// 0.1
let line = LineInfo::new_syllable(syllables);           // Vec<SyllableInfo>

// 0.2
let line = LineInfo::new_syllable(to_syllable_items(syllables));

就地修改合并音节

通过 sub_items_mut() 可以就地改子音节，聚合文本与时间随之变化：

use lyrics_helper::{FullSyllableInfo, SyllableInfo, SyllableItem};

// 同一单词内被合并的音节
let mut item = SyllableItem::from(FullSyllableInfo::new(vec![
    SyllableInfo::new("Hel".to_string(), 0, 500),
    SyllableInfo::new("lo".to_string(), 500, 1000),
]));
assert_eq!(item.text(), "Hello");

if let Some(full) = item.as_full_mut() {
    full.sub_items_mut()[0].text = "新文本".to_string();
}

assert_eq!(item.text(), "新文本lo");

Note

0.2 / 0.3 里聚合值是带缓存的，上面这段改完必须再调一次 refresh_properties()。0.4.0 移除了该缓存与这个方法，聚合值改为每次即时推导，所以这里不再需要任何失效操作。详见从 0.3 升级到 0.4。

类型检测行为变化

helpers::type_helper 对 Spotify、Apple Music、Musixmatch、网易云完整 YRC 与 QRC XML 的判定，改为真正解析 JSON/XML 结构，不再用 contains("...") 嗅探关键字。原先歌词正文里出现同名字符串会被误判的情况不再发生；如果你依赖过旧版的宽松判定，结果可能变严格。

其他

• lyrics-search 的 searchers 与 providers 整体置于 search feature 之下，关闭该 feature 时 crate 编译为空壳
• 搜索结果评分中，缺失的可选字段不再拉低总分，改为按可比较字段重新分配权重
• once_cell 已从依赖中移除，改用标准库的 LazyLock