API Data Structures

数据结构

LyricsData

歌词顶级模型容器：

pub struct LyricsData {
    pub file: Option<FileInfo>,                 // 文件格式及同步属性
    pub lines: Option<Vec<LineInfo>>,           // 歌词行列表
    pub writers: Option<Vec<String>>,           // 歌词作者列表
    pub track_metadata: Option<TrackMetadata>,  // 关联歌曲元数据
}

FileInfo 与 AdditionalFileInfo

pub struct FileInfo {
    #[serde(rename = "type")]
    pub lyrics_type: LyricsTypes,
    pub sync_types: SyncTypes,
    pub additional_info: Option<AdditionalFileInfo>,
}

AdditionalFileInfo 为枚举类型，包含三种变体：

• General(HashMap<String, String>)：通用属性键值对。
• Krc(KrcAdditionalInfo)：KRC 的专属解密特征与哈希信息。
• Spotify(SpotifyAdditionalInfo)：Spotify 的原生元数据。

LineInfo

歌词行核心枚举，包含四种变体：

pub enum LineInfo {
    // 基础行：纯文本 + 可选起止时间
    Line {
        text: String,
        start_time: Option<i32>,
        end_time: Option<i32>,
        alignment: LyricsAlignment,
        sub_line: Option<Box<LineInfo>>,
    },
    // 音节行：音节列表；行起止时间可选（为 None 时回退至首尾音节时间）
    Syllable {
        syllables: Vec<SyllableItem>,
        start_time: Option<i32>,
        end_time: Option<i32>,
        alignment: LyricsAlignment,
        sub_line: Option<Box<LineInfo>>,
    },
    // 完整基础行：基础行 + 多语言翻译 + 注音
    FullLine {
        text: String,
        start_time: Option<i32>,
        end_time: Option<i32>,
        alignment: LyricsAlignment,
        sub_line: Option<Box<LineInfo>>,
        translations: HashMap<String, String>,
        pronunciation: Option<String>,
    },
    // 完整音节行：音节行 + 多语言翻译 + 注音
    FullSyllable {
        syllables: Vec<SyllableItem>,
        start_time: Option<i32>,
        end_time: Option<i32>,
        alignment: LyricsAlignment,
        sub_line: Option<Box<LineInfo>>,
        translations: HashMap<String, String>,
        pronunciation: Option<String>,
    },
}

构造函数

• new_line(text, start, end) / new_line_simple(text) / new_line_with_time(text, start)
• new_syllable(syllables)：行时间为 None，起止时间取首尾音节。
• new_syllable_with_time(syllables, start, end)：显式指定独立的行起止时间（用于 QRC/KRC 行头时长）。
• new_full_line(text, start, end, translations, pronunciation)
• new_full_syllable(syllables, translations, pronunciation)

文本与时间读取

方法	说明
text() -> &str	获取行文本。注意：音节行内部没有独立文本字段，此方法返回空字符串。
text_from_any() -> String	通用文本读取：基础行返回其文本，音节行自动拼接所有音节字符。
full_text() -> String	包含子行（背景和声）的完整显示文本。子行文字以括号追加；若子行先于主行开始，则前置显示。
start_time() -> Option<i32>	行开始时间。音节行优先返回自身行时间，为 None 时回退至首个音节的开始时间。
end_time() -> Option<i32>	行结束时间。音节行优先返回自身行时间，为 None 时回退至末尾音节的结束时间。
duration() -> Option<i32>	持续时长（end_time - start_time）；仅当起止时间皆具备时返回 Some。
start_time_with_sub_line() / end_time_with_sub_line()	结合子行时间后的极值范围。

排序与比较语义

Warning

LineInfo 实现的 PartialEq、Eq 与 Ord 仅比较 start_time，完全忽略文本内容、音节切分与子行。这是为了支持 lines.sort() 的时间轴排序语义（对应上游 C# 的 IComparable）。

因此切勿使用 lines.contains(&line) 或 lines.dedup() 判断歌词内容是否重复；如有需要应显式比对 text_from_any()。两个均无开始时间的行判定为相等。

伴唱子行与翻译

• sub_line() -> Option<&LineInfo> / sub_line_mut() -> Option<&mut LineInfo>：获取伴唱子行（递归结构）。
• set_sub_line(Option<Box<LineInfo>>) / take_sub_line() -> Option<Box<LineInfo>>
• translations() -> Option<&HashMap<String, String>> / chinese_translation() -> Option<&str>
• pronunciation() -> Option<&str>：获取注音或罗马音。

SyllableInfo

单个音节的数据基元：

pub struct SyllableInfo {
    pub text: String,        // 音节文本
    pub start_time: i32,     // 开始时间（毫秒）
    pub end_time: i32,       // 结束时间（毫秒）
}

方法：duration(&self) -> i32。

SyllableItem 与 FullSyllableInfo

音节列表项抽象，对应上游 C# 的 ISyllableInfo：

pub enum SyllableItem {
    Syllable(SyllableInfo),      // 普通音节
    Full(FullSyllableInfo),      // 同一单词内合并的复合音节
}

Note

SyllableItem 未实现 PartialEq。如需比对两个音节的时间，应显式比较：a.start_time() == b.start_time() && a.end_time() == b.end_time()。

FullSyllableInfo 用于记录属于同一英文单词但拥有独立时间片段的连续音节（如 Apple Music、Musixmatch 逐字）：

pub struct FullSyllableInfo {
    pub sub_items: Vec<SyllableInfo>,
}

FullSyllableInfo 无内部可变性缓存，其 text()、start_time()、end_time() 等方法均在调用时根据 sub_items 即时聚合计算。整个歌词数据树天然满足 Send + Sync。

SyllableItem 常用方法：

• text() -> String：普通音节返回自身文本，合并音节返回各子音节拼接文本。
• start_time() -> i32 / end_time() -> i32 / duration() -> i32
• parts() -> &[SyllableInfo]：以扁平切片形式读取子音节（普通音节返回长度为 1 的切片，合并音节返回全部子项）。
• parts_mut() -> &mut [SyllableInfo]：就地修改音节列表。

TrackMetadata

歌曲与曲目元数据容器：

pub struct TrackMetadata {
    pub title: Option<String>,
    pub artist: Option<String>,             // 逗号分隔的艺术家文本
    pub album: Option<String>,
    pub album_artist: Option<String>,
    pub duration_ms: Option<i32>,
    pub isrc: Option<String>,
    pub language: Option<Vec<String>>,
    pub artists: Option<Vec<String>>,       // 结构化艺术家数组
    pub album_artists: Option<Vec<String>>,
    pub spotify_id: Option<String>,
}

辅助方法：

• new() -> Self：创建空元数据结构。
• ensure_artists()：若 artists 数组为空，自动将 artist 文本按逗号切分并填充。
• ensure_album_artists()：若 album_artists 为空，自动按逗号切分 album_artist。
• set_artist_from_list(Vec<String>)：同步写入 artist 与 artists。
• spotify_uri() -> Option<String>：返回 spotify:track:{id}。