lemony-lrc-parser 0.2.1__py3-none-any.whl

lemony_lrc_parser/__init__.py

@@ -0,0 +1,79 @@
+"""lemony-lrc-parser —— 简洁的 Python LRC 歌词解析器.
+
+公共 API 分成三层:
+
+1. **面向对象入口** (推荐) : :class:`Lyrics` 及其 :meth:`~Lyrics.loads` /
+   :meth:`~Lyrics.dumps` 方法.
+
+   .. code-block:: python
+
+       from lemony_lrc_parser import Lyrics
+
+       lyrics = Lyrics.loads(lrc_text)
+       for line in lyrics:
+           print(line.start, line.text)
+       lrc_out = lyrics.dumps()
+
+2. **顶层便捷函数** (等价于 :class:`Lyrics` 的方法) : :func:`loads` /
+   :func:`dumps`, 风格对齐 ``json`` / ``pickle``.
+
+   .. code-block:: python
+
+       import lemony_lrc_parser as llp
+
+       lyrics = llp.loads(lrc_text)
+       out = llp.dumps(lyrics)
+
+3. **底层函数与工具**: :func:`parse_lrc` / :func:`parse_line` / :func:`dump_lrc`
+   以及时间标签工具 :func:`format_timetag` / :func:`parse_timetag`.
+"""
+
+from __future__ import annotations
+
+from .exceptions import InvalidLyricsError, LyricsParserError
+from .models import BasicLyricLine, LyricLine, Lyrics, LyricWord
+from .parser import parse_line, parse_lrc
+from .serializer import dump_lrc
+from .timetag import format_timetag, parse_timetag
+
+__all__ = [
+    "BasicLyricLine",
+    "LyricLine",
+    "LyricWord",
+    "Lyrics",
+    "InvalidLyricsError",
+    "LyricsParserError",
+    "dumps",
+    "loads",
+    "dump_lrc",
+    "parse_line",
+    "parse_lrc",
+    "format_timetag",
+    "parse_timetag",
+]
+
+
+def loads(s: str, *, fill_implicit_line_end: bool = False) -> Lyrics:
+    """从 LRC 字符串解析出一份 :class:`Lyrics`.
+
+    等价于 :meth:`Lyrics.loads`.
+    """
+    return Lyrics.loads(s, fill_implicit_line_end=fill_implicit_line_end)
+
+
+def dumps(
+    lyrics: Lyrics,
+    *,
+    with_metadata: bool = True,
+    use_bracket_for_byword_tag: bool = False,
+    apply_offset_from_metadata: bool = False,
+) -> str:
+    """把 :class:`Lyrics` 序列化为 LRC 字符串.
+
+    等价于 ``lyrics.dumps(**kwargs)``
+    """
+    return lyrics.dumps(
+        with_metadata=with_metadata,
+        use_bracket_for_byword_tag=use_bracket_for_byword_tag,
+        apply_offset_from_metadata=apply_offset_from_metadata,
+    )

lemony_lrc_parser/exceptions.py

@@ -0,0 +1,6 @@
+class LyricsParserError(Exception):
+    pass
+
+
+class InvalidLyricsError(LyricsParserError):
+    pass

lemony_lrc_parser/models.py

@@ -0,0 +1,184 @@
+"""数据模型.
+
+定义 LRC 歌词的核心数据结构: :class:`LyricWord`、:class:`LyricLine` 和
+作为顶层容器的 :class:`Lyrics`.
+
+本模块只承载数据层语义; 解析 (LRC 文本 → :class:`Lyrics`) 与序列化
+ (:class:`Lyrics` → LRC 文本) 的实现分别位于 :mod:`.parser` 与
+:mod:`.serializer`, 这里仅通过延迟导入把它们暴露成 :class:`Lyrics` 的方法.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from copy import deepcopy
+from dataclasses import dataclass, field
+from typing import overload
+
+__all__ = [
+    "BasicLyricLine",
+    "LyricLine",
+    "LyricWord",
+    "Lyrics",
+]
+
+
+@dataclass
+class LyricWord:
+    """一个歌词词元 (可以是一个字、一个词, 或整行纯文本) .
+
+    Attributes:
+        content: 词元的文本内容.
+        start: 开始时间 (毫秒) , 未知时为 ``None``.
+        end: 结束时间 (毫秒) , 未知时为 ``None``.
+    """
+
+    content: str = ""
+    start: int | None = None
+    end: int | None = None
+
+
+#: 一行歌词主体 (由若干 :class:`LyricWord` 组成的线性序列) .
+#:
+#: 对于单段整行歌词, 此列表长度通常为 1; 对于逐字歌词, 长度为各词元数量.
+BasicLyricLine = list[LyricWord]
+
+
+@dataclass
+class LyricLine:
+    """一行歌词.
+
+    Attributes:
+        start: 行开始时间 (毫秒) .
+        end: 行结束时间 (毫秒) .
+        content: 主语言行内容, 见 :data:`BasicLyricLine`.
+        reference_lines: 参考行列表, 常用于存放翻译/音译等辅助行.
+    """
+
+    start: int | None = None
+    end: int | None = None
+    content: BasicLyricLine = field(default_factory=list)
+    reference_lines: list[BasicLyricLine] = field(default_factory=list)
+
+    @property
+    def text(self) -> str:
+        """拼接整行主语言的纯文本 (便于日志与简单展示) ."""
+        return "".join(word.content for word in self.content)
+
+
+@dataclass
+class Lyrics:
+    """一份完整的歌词.
+
+    Attributes:
+        lines: 按时间顺序排列的歌词行.
+        metadata: 元数据键值对 (如 ``ti``、``ar``、``offset`` 等) .
+
+    :class:`Lyrics` 同时是序列容器, 可直接 ``for line in lyrics`` 迭代、
+    ``len(lyrics)`` 取行数, 或通过下标/切片访问具体行.
+    """
+
+    lines: list[LyricLine] = field(default_factory=list)
+    metadata: dict[str, str] = field(default_factory=dict)
+
+    def __iter__(self) -> Iterator[LyricLine]:
+        return iter(self.lines)
+
+    def __len__(self) -> int:
+        return len(self.lines)
+
+    @overload
+    def __getitem__(self, index: int) -> LyricLine: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[LyricLine]: ...
+
+    def __getitem__(self, index: int | slice) -> LyricLine | list[LyricLine]:
+        return self.lines[index]
+
+    def __add__(self, other: Lyrics) -> Lyrics:
+        if not isinstance(other, Lyrics):
+            return NotImplemented
+        return self.combine(other)
+
+    def combine(self, other: Lyrics, *, other_as_refline_only: bool = True) -> Lyrics:
+        """将另一份 :class:`Lyrics` 合并进当前对象, 返回新实例.
+
+        常见用途是把翻译版本合并到主歌词: 翻译的每一行会被挂在 ``self`` 中
+        同 ``start`` 行的 :attr:`LyricLine.reference_lines` 列表里.
+
+        Args:
+            other: 要合并进来的另一份歌词.
+            other_as_refline_only: 若为 ``True`` (默认) , ``other`` 中在
+                ``self`` 里找不到对应时间点的行会被丢弃; 若为 ``False``,
+                这些行会被保留为新行.
+
+        Returns:
+            合并后的新 :class:`Lyrics` 对象; ``self`` 与 ``other`` 均不受影响.
+        """
+        new = Lyrics()
+        # metadata 以 self 为准, other 作为补充
+        new.metadata.update(other.metadata)
+        new.metadata.update(self.metadata)
+
+        pool: dict[int, LyricLine] = {}
+        for line in self.lines:
+            if line.start is None:
+                continue
+            # 深拷贝 self 的行, 避免污染原始对象
+            pool[line.start] = deepcopy(line)
+        for line in other.lines:
+            if line.start is None:
+                continue
+            if line.start in pool:
+                # 深拷贝 other 的行内容, 避免共享引用
+                pool[line.start].reference_lines.append(deepcopy(line.content))
+                pool[line.start].reference_lines.extend(
+                    deepcopy(rl) for rl in line.reference_lines
+                )
+            elif not other_as_refline_only:
+                pool[line.start] = deepcopy(line)
+
+        new.lines = list(pool.values())
+        return new
+
+    @classmethod
+    def loads(cls, s: str, *, fill_implicit_line_end: bool = False) -> Lyrics:
+        """从 LRC 字符串解析出一份 :class:`Lyrics`.
+
+        Args:
+            s: LRC 源文本.
+            fill_implicit_line_end: 若为 ``True``, 则当某行没有显式结束时间时,
+                自动用下一行的开始时间作为其结束时间.
+        """
+        from .parser import parse_lrc
+
+        return parse_lrc(s, fill_implicit_line_end=fill_implicit_line_end)
+
+    def dumps(
+        self,
+        *,
+        with_metadata: bool = True,
+        use_bracket_for_byword_tag: bool = False,
+        apply_offset_from_metadata: bool = False,
+    ) -> str:
+        """把当前对象序列化为 LRC 字符串.
+
+        Args:
+            with_metadata: 是否写出 metadata 段.
+            use_bracket_for_byword_tag: 逐字标签是否使用 ``[...]``
+                 (默认 ``False`` 使用 ``<...>``) .
+            apply_offset_from_metadata: 是否读取并应用 ``metadata.offset``;
+                见 :func:`.serializer.dump_lrc` 的完整语义说明.
+        """
+        from .serializer import dump_lrc
+
+        return dump_lrc(
+            self,
+            with_metadata=with_metadata,
+            use_bracket_for_byword_tag=use_bracket_for_byword_tag,
+            apply_offset_from_metadata=apply_offset_from_metadata,
+        )
+
+    def __str__(self) -> str:
+        return self.dumps()

lemony_lrc_parser/parser.py

@@ -0,0 +1,291 @@
+"""LRC 解析器.
+
+将 LRC 文本转换为 :class:`.models.Lyrics`. 公共入口有:
+
+* :func:`parse_line` —— 解析单行歌词 (不含行首的重复时间标签) .
+* :func:`parse_lrc`  —— 解析整份 LRC 文本.
+
+其它以下划线开头的函数均为内部实现细节, 后续版本可能调整.
+"""
+
+from __future__ import annotations
+
+import re
+from copy import deepcopy
+from logging import getLogger
+
+from .exceptions import LyricsParserError
+from .models import BasicLyricLine, LyricLine, Lyrics, LyricWord
+from .regex import (
+    GENERIC_TIMETAG_REGEX,
+    LINE_TIMETAG_REGEX,
+    METATAG_REGEX,
+    compile_regex,
+)
+from .timetag import _match_to_ms
+
+logger = getLogger(__name__)
+
+__all__ = [
+    "parse_line",
+    "parse_lrc",
+]
+
+
+def parse_line(line: str) -> BasicLyricLine | None:
+    """解析单行歌词为 :data:`.models.BasicLyricLine`.
+
+    输入行应已经去除了行首的重复行时间标签 (见 :func:`_split_leading_line_timetags`) .
+    若该行为空或只含空白, 返回 ``None``.
+
+    内部算法:
+        1. 用通用时间标签正则把原行拆成 ``text/match`` 交替序列.
+        2. 把序列拆成 ``texts`` (长度 N) 与 ``times`` (长度 N-1) 两条平行数组.
+        3. 丢弃非单调递增的时间标签 (视为误写并合并相邻文本) .
+        4. 用滑动窗口方式把 ``texts[i]`` 和 ``times[i-1] / times[i]`` 绑成
+           单个 :class:`LyricWord`.
+        5. 去掉首尾的空词, 使 ``result[0].start`` 成为行首、
+           ``result[-1].end`` 成为行尾.
+    """
+    if not line.strip():
+        return None
+
+    sequence = _split_on_timetags(line)
+    if not sequence or (len(sequence) == 1 and not sequence[0]):
+        return None
+
+    if len(sequence) % 2 != 1:
+        raise LyricsParserError(
+            f"Unexpected sequence length (expected odd): {len(sequence)}"
+        )
+
+    texts, times = _unzip_sequence(sequence)
+
+    # 只有一段纯文本、没有任何时间标签
+    if len(texts) == 1:
+        if times:
+            raise LyricsParserError(
+                "Inconsistent state: single text segment should not have time tags"
+            )
+        return [LyricWord(content=texts[0])]
+
+    diff = len(texts) - len(times)
+    if diff != 1:
+        raise LyricsParserError(
+            f"text/time length mismatch: expected diff=1, got {diff}"
+        )
+
+    texts, times = _drop_nonmonotonic_times(texts, times)
+
+    result: BasicLyricLine = []
+    last_idx = len(texts) - 1
+    for idx, content in enumerate(texts):
+        word = LyricWord(content=content)
+        if idx > 0:
+            word.start = times[idx - 1]
+        if idx < last_idx:
+            word.end = times[idx]
+        result.append(word)
+
+    if len(result) < 2:
+        raise LyricsParserError(
+            f"Expected at least 2 preprocessed elements, got {len(result)}"
+        )
+
+    # 去除空头/空尾, 使 [0].start 与 [-1].end 分别对应行首/行尾
+    if not result[0].content:
+        result.pop(0)
+    if not result[-1].content and len(result) > 1:
+        result.pop(-1)
+
+    return result
+
+
+def _split_on_timetags(text: str) -> list[str | re.Match[str]]:
+    """按通用时间标签把一行文本拆分为 ``[text, match, text, match, ..., text]``.
+
+    返回结果长度始终为奇数: 以文本开头、以文本结尾, 中间夹杂 match 对象.
+    若相邻的两个 match 之间没有文本, 会插入空字符串, 保证 text/match 严格交替.
+    """
+    pattern = compile_regex(GENERIC_TIMETAG_REGEX)
+    result: list[str | re.Match[str]] = []
+    last_end = 0
+    for match in pattern.finditer(text):
+        result.append(text[last_end : match.start()])
+        result.append(match)
+        last_end = match.end()
+    result.append(text[last_end:])
+    return result
+
+
+def _unzip_sequence(
+    sequence: list[str | re.Match[str]],
+) -> tuple[list[str], list[int]]:
+    """把 :func:`_split_on_timetags` 的结果拆成两条独立数组."""
+    texts: list[str] = []
+    times: list[int] = []
+    for item in sequence:
+        if isinstance(item, str):
+            texts.append(item)
+        elif isinstance(item, re.Match):
+            times.append(_match_to_ms(item))
+        else:
+            raise LyricsParserError(
+                f"Unexpected element type in sequence: {type(item).__name__}"
+            )
+    return texts, times
+
+
+def _drop_nonmonotonic_times(
+    texts: list[str], times: list[int]
+) -> tuple[list[str], list[int]]:
+    """丢弃非严格递增的时间标签, 并把它们前后的文本合并."""
+    texts = list(texts)
+    times = list(times)
+    removed = 0
+    for raw_idx in range(len(times)):
+        idx = raw_idx - removed
+        if idx <= 0:
+            continue
+        prev_time = times[idx - 1]
+        now_time = times[idx]
+        if prev_time < now_time:
+            continue
+        logger.warning(f"Unordered time tag dropped: prev={prev_time}, now={now_time}")
+        texts[idx] += texts[idx + 1]
+        texts.pop(idx + 1)
+        times.pop(idx)
+        removed += 1
+    return texts, times
+
+
+def parse_lrc(lrc: str, *, fill_implicit_line_end: bool = False) -> Lyrics:
+    """解析一份完整的 LRC 文本.
+
+    Args:
+        lrc: LRC 源文本.
+        fill_implicit_line_end: 若为 ``True``, 则对没有显式结束时间的行,
+            用紧随其后的行开始时间作为隐式结束时间.
+
+    Returns:
+        组装完毕的 :class:`Lyrics` 对象.
+    """
+    metadata: dict[str, str] = {}
+    line_pool: dict[int, LyricLine] = {}
+    last_tag: int | None = None
+
+    for raw_line in lrc.strip().splitlines():
+        line_str = raw_line.strip()
+
+        # 1. metadata 行 (如 [ti: ...]、[offset: 500])
+        if meta := _extract_metadata(line_str):
+            metadata.update(meta)
+            logger.debug(f"Metadata line: {line_str!r}")
+            continue
+
+        logger.debug(f"Parsing lyric line: {line_str!r}")
+
+        # 2. 切出行首的重复时间标签
+        time_tags, line_str = _split_leading_line_timetags(line_str)
+        line = parse_line(line_str)
+
+        # 2a. 行首没有时间标签 → 要么是参考行, 要么是分隔符
+        if not time_tags:
+            if not line:
+                # 空分隔行, 重置参考行锚点
+                last_tag = None
+                logger.debug("Reference line marker reset")
+                continue
+            if last_tag is None:
+                logger.warning(
+                    f"Orphaned lyric line (no anchor): {line!r} (raw={raw_line!r})"
+                )
+                continue
+            logger.debug(f"Adding {line!r} as reference of {line_pool[last_tag]!r}")
+            line_pool[last_tag].reference_lines.append(line)
+            continue
+
+        # 2b. 行首有时间标签但没有正文 → 占位符 (例如清空当前歌词)
+        if not line:
+            t = time_tags[0]
+            if t not in line_pool:
+                line_pool[t] = LyricLine(start=t, content=[LyricWord(content="")])
+            continue
+
+        # 2c. 常规行: 可能有多个重复时间标签, 每个都生成一行
+        _register_line_at_tags(line_pool, line, time_tags)
+        last_tag = time_tags[0] if len(time_tags) == 1 else None
+
+    return _finalize_lyrics(
+        metadata, line_pool, fill_implicit_line_end=fill_implicit_line_end
+    )
+
+
+def _register_line_at_tags(
+    line_pool: dict[int, LyricLine],
+    line: BasicLyricLine,
+    time_tags: list[int],
+) -> None:
+    """把同一行歌词注册到 ``line_pool`` 中所有 ``time_tags`` 对应的时间点上."""
+    word_start = line[0].start
+    for tag in time_tags:
+        if word_start is not None and word_start < tag:
+            logger.warning(
+                f"Invalid duplicate line tag {tag}ms "
+                f"(later than first word start {word_start}ms)"
+            )
+            continue
+        if tag in line_pool:
+            # 同一个时间点已有行 → 当前行变为参考行
+            line_pool[tag].reference_lines.append(line)
+        else:
+            # 深拷贝 word 列表, 避免多个 LyricLine 共享同一 LyricWord 实例
+            line_pool[tag] = LyricLine(content=[deepcopy(word) for word in line])
+
+
+def _finalize_lyrics(
+    metadata: dict[str, str],
+    line_pool: dict[int, LyricLine],
+    *,
+    fill_implicit_line_end: bool,
+) -> Lyrics:
+    """把 ``line_pool`` 按时间排序、补全行首/行尾时间并装进 :class:`Lyrics`."""
+    lyrics = Lyrics(metadata=metadata)
+    sorted_items = sorted(line_pool.items(), key=lambda kv: kv[0])
+
+    for idx, (line_start, line) in enumerate(sorted_items):
+        line.start = line_start
+
+        # 把最后一个 word 的 end 提升为整行 end
+        last_word = line.content[-1]
+        if last_word.end is not None:
+            line.end, last_word.end = last_word.end, None
+
+        # 可选: 用下一行的开始时间作为当前行的隐式结束
+        if fill_implicit_line_end and line.end is None and idx + 1 < len(sorted_items):
+            line.end = sorted_items[idx + 1][0]
+
+        lyrics.lines.append(line)
+
+    return lyrics
+
+
+def _split_leading_line_timetags(raw_line: str) -> tuple[list[int], str]:
+    """从一行开头连续剥离 ``[mm:ss.xxx]`` 行时间标签.
+
+    Returns:
+        ``(times, remainder)``, ``times`` 为毫秒列表, ``remainder`` 为剥离后
+        的剩余文本.
+    """
+    pattern = compile_regex(f"^{LINE_TIMETAG_REGEX}")
+    times: list[int] = []
+    while (match := pattern.match(raw_line)) is not None:
+        times.append(_match_to_ms(match))
+        raw_line = raw_line[match.end() :]
+    return times, raw_line
+
+
+def _extract_metadata(line: str) -> dict[str, str]:
+    """从一行字符串中提取 metadata 标签 ``[key: value]``."""
+    pattern = compile_regex(METATAG_REGEX)
+    return {match["key"]: match["value"] for match in pattern.finditer(line)}

lemony_lrc_parser/regex.py

@@ -0,0 +1,159 @@
+"""正则表达式常量与编译缓存.
+
+本模块集中存放 LRC 语法所需的正则模式, 并提供带缓存的 :func:`compile_regex`.
+这些常量会被 :mod:`.parser`、:mod:`.timetag` 等模块消费, 不建议外部直接依赖.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "GENERIC_TIMETAG_REGEX",
+    "LINE_TIMETAG_REGEX",
+    "METATAG_REGEX",
+    "TIMETAG_REGEX_STRICT",
+    "WORD_TIMETAG_REGEX",
+    "compile_regex",
+]
+
+_REGEX_PATTERN_CACHE: dict[str, re.Pattern[str]] = {}
+
+
+def compile_regex(pattern: str) -> re.Pattern[str]:
+    """使用 ``re.VERBOSE`` 编译正则, 并以模式字符串为 key 做进程级缓存."""
+    compiled = _REGEX_PATTERN_CACHE.get(pattern)
+    if compiled is None:
+        compiled = re.compile(pattern, flags=re.VERBOSE)
+        _REGEX_PATTERN_CACHE[pattern] = compiled
+    return compiled
+
+
+#: 行时间标签 ``[mm:ss.xxx]``, 命名组: ``min`` / ``sec`` / ``tail``.
+LINE_TIMETAG_REGEX: str = r"""
+    (?:
+        \[
+            \s*
+                (?P<min>\d{1,4})
+            \s*
+            :
+            \s*
+                (?P<sec>\d{1,2})
+            \s*
+            (?:
+                [:\.]
+                \s*
+                    (?P<tail>\d{1,6})
+                \s*
+            )?
+        \]
+    )
+"""
+
+#: 逐字时间标签 ``<mm:ss.xxx>``, 命名组: ``min`` / ``sec`` / ``tail``.
+WORD_TIMETAG_REGEX: str = r"""
+    (?:
+        \<
+            \s*
+                (?P<min>\d{1,4})
+            \s*
+            :
+            \s*
+                (?P<sec>\d{1,2})
+            \s*
+            (?:
+                [:\.]
+                \s*
+                    (?P<tail>\d{1,6})
+                \s*
+            )?
+        \>
+    )
+"""
+
+#: 严格行时间标签 ``[mm:ss.xxx]``, 要求三段齐全、毫秒 1-3 位、无多余空白.
+TIMETAG_REGEX_STRICT: str = r"""
+    (?:
+        \[
+            (?P<min>\d{1,4})
+            :
+            (?P<sec>\d{1,2})
+            \.
+            (?P<tail>\d{1,3})
+        \]
+    )
+"""
+
+#: 元数据标签 ``[key: value]``, 命名组: ``key`` / ``value``.
+METATAG_REGEX: str = r"""
+    (?:
+        \[
+            \s*
+            (?P<key>[a-zA-Z#]{2,16})  # `#` 用于注释标签, 见 LRC 规范
+            \s*
+            :
+            \s*
+            (?P<value>.+?)
+            \s*
+        \]
+    )
+"""
+
+#: 通用时间标签 (同时匹配方括号行标签与尖括号逐字标签) .
+#:
+#: 为避免同名命名组冲突, 方括号分支使用 ``line_*`` 前缀,
+#: 尖括号分支使用 ``word_*`` 前缀. 消费方应使用 :func:`._match_to_ms` 抹平差异.
+GENERIC_TIMETAG_REGEX: str = r"""
+    (?:
+        (?:
+            \[
+                \s*
+                    (?P<line_min>\d{1,4})
+                \s*
+                :
+                \s*
+                    (?P<line_sec>\d{1,2})
+                \s*
+                (?:
+                    [:\.]
+                    \s*
+                        (?P<line_tail>\d{1,6})
+                    \s*
+                )?
+            \]
+        )
+        |
+        (?:
+            \<
+                \s*
+                    (?P<word_min>\d{1,4})
+                \s*
+                :
+                \s*
+                    (?P<word_sec>\d{1,2})
+                \s*
+                (?:
+                    [:\.]
+                    \s*
+                        (?P<word_tail>\d{1,6})
+                    \s*
+                )?
+            \>
+        )
+    )
+"""
+
+
+def _warmup_cache() -> None:
+    """在模块导入期预热编译缓存, 避免首次使用时的抖动."""
+    for pattern in (
+        LINE_TIMETAG_REGEX,
+        WORD_TIMETAG_REGEX,
+        TIMETAG_REGEX_STRICT,
+        METATAG_REGEX,
+        GENERIC_TIMETAG_REGEX,
+    ):
+        compile_regex(pattern)
+
+
+_warmup_cache()

lemony_lrc_parser/serializer.py

@@ -0,0 +1,215 @@
+"""LRC 序列化器.
+
+把 :class:`.models.Lyrics` 对象序列化为 LRC 文本. 公共入口是
+:func:`dump_lrc`
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from io import StringIO
+from logging import getLogger
+
+from .models import BasicLyricLine, Lyrics
+from .timetag import format_timetag
+
+logger = getLogger(__name__)
+
+__all__ = [
+    "dump_lrc",
+]
+
+
+def dump_lrc(
+    lyrics: Lyrics,
+    *,
+    with_metadata: bool = True,
+    use_bracket_for_byword_tag: bool = False,
+    apply_offset_from_metadata: bool = False,
+) -> str:
+    """把一份 :class:`Lyrics` 序列化为 LRC 文本.
+
+    Args:
+        lyrics: 待序列化的歌词对象.
+        with_metadata: 是否写出 metadata 段 (不影响 offset 的处理逻辑) .
+        use_bracket_for_byword_tag: 若为 ``True``, 逐字标签使用 ``[...]``;
+            否则使用 ``<...>``.
+        apply_offset_from_metadata: 是否读取并应用 ``metadata.offset``.
+            见下方“offset 语义”.
+
+    offset 语义 (与 LRC 规范一致) :
+        正 offset 会让歌词显示提前, 即 ``display_time = tag_time - offset``.
+        当 ``offset > 0`` 时, 最早的时间戳可能变为负数; 此时函数只应用
+        ``min(all_times)`` 这部分“安全” offset, 把剩余量写回
+        ``metadata.offset`` 交给播放器处理, 确保输出的所有时间标签 ``>= 0``.
+    """
+    buffer = StringIO()
+
+    # 拷贝 metadata 以免污染调用方传入的对象
+    metadata = dict(lyrics.metadata)
+    offset = _resolve_offset(
+        lyrics, metadata, apply_offset_from_metadata=apply_offset_from_metadata
+    )
+
+    if with_metadata:
+        for key, value in metadata.items():
+            buffer.write(f"[{key}: {value}]\n")
+
+    for idx, line in enumerate(lyrics.lines):
+        if idx > 0:
+            buffer.write("\n")
+
+        line_start = line.start
+        if line_start is None:
+            logger.warning(f"Skipping line with unknown start time: {line}")
+            continue
+
+        # 写主行
+        buffer.write(format_timetag(line_start - offset))
+        buffer.write(
+            _format_words(
+                line.content,
+                line_start=line_start,
+                offset=offset,
+                use_bracket_for_byword_tag=use_bracket_for_byword_tag,
+            )
+        )
+        if line.end is not None:
+            buffer.write(format_timetag(line.end - offset))
+        buffer.write("\n")
+
+        # 写参考行 (共享主行的 start)
+        for refline in line.reference_lines:
+            buffer.write(format_timetag(line_start - offset))
+            buffer.write(
+                _format_words(
+                    refline,
+                    line_start=line_start,
+                    offset=offset,
+                    use_bracket_for_byword_tag=use_bracket_for_byword_tag,
+                )
+            )
+            buffer.write("\n")
+
+    return buffer.getvalue()
+
+
+def _format_words(
+    words: BasicLyricLine,
+    *,
+    line_start: int | None,
+    offset: int,
+    use_bracket_for_byword_tag: bool,
+) -> str:
+    """把一行 :data:`BasicLyricLine` 格式化为字符串 (不含行首/行末标签) .
+
+    逐字标签在以下情形会被省略:
+
+    * ``idx == 0`` 且 ``word.start == line_start`` —— 行首时间已由调用方
+      输出过, 不重复.
+    * ``idx > 0`` 且 ``words[idx - 1].end == word.start`` —— 与前一词的
+      结束时间相接, 可省略前缀.
+    """
+    use_angle = not use_bracket_for_byword_tag
+    parts: list[str] = []
+
+    for idx, word in enumerate(words):
+        prefix = ""
+        suffix = ""
+
+        if word.start is not None:
+            if idx == 0:
+                if word.start != line_start:
+                    prefix = format_timetag(
+                        word.start - offset, use_angle_bracket=use_angle
+                    )
+            elif words[idx - 1].end != word.start:
+                prefix = format_timetag(
+                    word.start - offset, use_angle_bracket=use_angle
+                )
+
+        if word.end is not None:
+            suffix = format_timetag(word.end - offset, use_angle_bracket=use_angle)
+
+        parts.append(f"{prefix}{word.content}{suffix}")
+
+    return "".join(parts)
+
+
+def _resolve_offset(
+    lyrics: Lyrics,
+    metadata: dict[str, str],
+    *,
+    apply_offset_from_metadata: bool,
+) -> int:
+    """决定实际应用的 offset 值, 必要时把剩余部分写回 ``metadata``.
+
+    Args:
+        lyrics: 原始歌词对象 (只读, 用于收集时间戳) .
+        metadata: 调用方已经拷贝出的 metadata 字典.
+            ``offset`` 键可能被 pop 出来 (``apply_offset_from_metadata=True``
+            时) 或更新为剩余 offset.
+        apply_offset_from_metadata: 是否启用 offset 处理.
+
+    Returns:
+        实际应从每个时间戳中扣除的毫秒数, 保证不会让任何时间戳变为负.
+    """
+    if not apply_offset_from_metadata:
+        return 0
+
+    offset_str = metadata.pop("offset", None)
+    if not offset_str:
+        return 0
+
+    try:
+        offset = int(offset_str)
+    except ValueError:
+        logger.warning(
+            f"Cannot parse metadata.offset as integer, ignoring: {offset_str!r}"
+        )
+        return 0
+
+    logger.info(f"Applying global time offset: {offset}ms (from metadata.offset)")
+
+    # 负 offset 只会让时间戳整体变大, 无需做越界保护
+    if offset <= 0:
+        return offset
+
+    all_times = list(_iter_all_timestamps(lyrics))
+    if not all_times:
+        return offset
+
+    min_time = min(all_times)
+    if min_time - offset >= 0:
+        return offset
+
+    # 正 offset 超过最小时间戳 → 只应用“安全”部分, 剩余写回 metadata
+    remaining = offset - min_time
+    logger.warning(
+        f"Applying offset={offset}ms would make minimum timestamp {min_time}ms "
+        f"negative; only applying {min_time}ms, remaining {remaining}ms kept in "
+        f"metadata.offset"
+    )
+    metadata["offset"] = str(remaining)
+    return min_time
+
+
+def _iter_all_timestamps(lyrics: Lyrics) -> Iterator[int]:
+    """迭代 :class:`Lyrics` 中出现过的所有时间戳 (含参考行) ."""
+    for line in lyrics.lines:
+        if line.start is not None:
+            yield line.start
+        if line.end is not None:
+            yield line.end
+        yield from _iter_word_timestamps(line.content)
+        for refline in line.reference_lines:
+            yield from _iter_word_timestamps(refline)
+
+
+def _iter_word_timestamps(words: BasicLyricLine) -> Iterator[int]:
+    """从一个 word 序列中迭代出所有非空时间戳."""
+    for word in words:
+        if word.start is not None:
+            yield word.start
+        if word.end is not None:
+            yield word.end

lemony_lrc_parser/timetag.py

@@ -0,0 +1,86 @@
+"""时间标签处理工具.
+
+集中管理 LRC 时间标签 (``[mm:ss.xxx]`` / ``<mm:ss.xxx>``) 的解析与格式化.
+"""
+
+from __future__ import annotations
+
+import re
+from logging import getLogger
+
+from .regex import TIMETAG_REGEX_STRICT, compile_regex
+
+logger = getLogger(__name__)
+
+__all__ = [
+    "format_timetag",
+    "parse_timetag",
+]
+
+
+def format_timetag(
+    ms: int,
+    *,
+    use_angle_bracket: bool = False,
+    tail_digits: int = 3,
+) -> str:
+    """将毫秒数格式化为 LRC 时间标签字符串.
+
+    Args:
+        ms: 毫秒时间戳 (允许为负, 调用方应自行保证语义合理) .
+        use_angle_bracket: True 使用 ``<...>`` (逐字标签) , False 使用 ``[...]`` (行标签) .
+        tail_digits: 毫秒尾部补齐的位数, 默认为 3.
+
+    Returns:
+        形如 ``[01:23.456]`` 或 ``<01:23.456>`` 的字符串.
+    """
+    if ms < 0:
+        raise ValueError(f"Negative timestamp is not allowed: {ms}ms")
+    minutes = ms // 60_000
+    seconds = (ms % 60_000) // 1000
+    millis = ms % 1000
+    body = f"{minutes:02d}:{seconds:02d}.{millis:0{tail_digits}d}"
+    return f"<{body}>" if use_angle_bracket else f"[{body}]"
+
+
+def parse_timetag(s: str) -> int | None:
+    """解析一个严格格式的时间标签字符串, 返回对应毫秒数.
+
+    严格格式要求形如 ``[mm:ss.xxx]`` (方括号、三段齐全、毫秒 1-3 位) .
+    解析失败返回 ``None``.
+    """
+    match = compile_regex(rf"^{TIMETAG_REGEX_STRICT}$").match(s)
+    return _match_to_ms(match) if match else None
+
+
+def _match_to_ms(match: re.Match[str]) -> int:
+    """从正则匹配对象中提取毫秒数.
+
+    兼容两类命名组:
+
+    * 标准命名组 ``min`` / ``sec`` / ``tail`` (见 ``LINE_TIMETAG_REGEX`` 等) .
+    * 前缀命名组 ``line_min`` / ``word_min`` 等 (见 ``GENERIC_TIMETAG_REGEX``) .
+
+    该函数是包内部工具, 不导出到公共 API.
+    """
+    groups = match.groupdict()
+
+    # 优先使用前缀命名组, 再退回到标准命名组
+    min_val = groups.get("line_min") or groups.get("word_min") or groups.get("min")
+    sec_val = groups.get("line_sec") or groups.get("word_sec") or groups.get("sec")
+    tail_val = groups.get("line_tail") or groups.get("word_tail") or groups.get("tail")
+
+    minutes = int(min_val or 0)
+    seconds = int(sec_val or 0)
+
+    if tail_val:
+        # 将毫秒标准化到 3 位
+        if len(tail_val) > 3:
+            tail_val = tail_val[:3]  # 截断: "123456" -> "123"
+        elif len(tail_val) < 3:
+            tail_val = tail_val.ljust(3, "0")  # 补齐: "1" -> "100"
+        millis = int(tail_val)
+    else:
+        millis = 0
+
+    return millis + seconds * 1000 + minutes * 60_000

lemony_lrc_parser-0.2.1.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: lemony-lrc-parser
+Version: 0.2.1
+Summary: A simple LRC parser for Python.
+Project-URL: Homepage, https://github.com/NingmengLemon/lemony-lrc-parser
+Project-URL: Repository, https://github.com/NingmengLemon/lemony-lrc-parser.git
+Project-URL: Issues, https://github.com/NingmengLemon/lemony-lrc-parser/issues
+Author-email: LemonekoUwU <lemoneko233uwu@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: Enhanced LRC,LRC,SPL,lyrics,parser,serializer
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: <3.16,>=3.9
+Description-Content-Type: text/markdown
+
+# Lemony LRC Parser
+
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI](https://img.shields.io/pypi/v/lemony-lrc-parser)](https://pypi.org/project/lemony-lrc-parser/)
+
+柠檬味的 Python LRC 歌词解析器.
+
+Lemon-flavored LRC Parser for Python.
+
+## Features
+
+- 解析标准 LRC 歌词文件
+- 支持 EnhancedLRC / SPL 的逐字歌词标签
+- 支持 metadata 标签
+- 支持折叠时间标签
+- 支持参照行
+- 支持歌词合并
+- 完整的类型注解
+
+## Installation
+
+推荐使用 [uv](https://docs.astral.sh/uv/).
+
+It's recommend to use [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv add lemony-lrc-parser
+```
+
+用 pip 也行.
+
+It's okay to use pip.
+
+```bash
+pip install lemony-lrc-parser
+```
+
+## Usage
+
+### Quick Start
+
+```python
+import lemony_lrc_parser as llp
+
+lrc_text = """[ti: Never Gonna Give You Up]
+[ar: Rick Astley]
+
+[00:18.684]We're no strangers to love
+[00:18.684]我们都是情场老手
+
+[00:22.657]You know the rules and so do I
+[00:22.657]你和我都知道爱情的规则
+
+[00:27.070]A full commitment's what I'm thinking of
+[00:27.070]我在想的正是一份实打实的承诺
+
+[00:31.459]You wouldn't get this from any other guy
+[00:31.459]你从其他人那里得不到的
+"""
+
+# 解析
+lyrics = llp.loads(lrc_text)
+
+# 访问 metadata
+print(lyrics.metadata["ti"])  # "Never Gonna Give You Up"
+print(lyrics.metadata["ar"])  # "Rick Astley"
+
+# 遍历歌词行
+for line in lyrics:
+    print(f"{line.start}ms: {line.text}")
+
+# 序列化回 LRC 文本
+output = llp.dumps(lyrics)
+```
+
+### OOP Interface
+
+`Lyrics` 类提供面向对象的解析和序列化入口:
+
+```python
+from lemony_lrc_parser import Lyrics
+
+lyrics = Lyrics.loads(lrc_text)
+
+# Lyrics 同时是序列容器
+print(len(lyrics))    # 行数
+print(lyrics[0].text) # 第一行文本
+print(lyrics[-1].text)
+
+# 切片访问
+first_three = lyrics[0:3]
+
+# 序列化
+lrc_output = lyrics.dumps()
+
+# __str__ 等价于 dumps()
+print(lyrics)
+```
+
+### Word-level Lyrics
+
+解析逐字 (Enhanced LRC / SPL) 歌词:
+
+```python
+lrc_text = "[00:01.000]<00:01.000>Never <00:01.500>gonna <00:02.000>give <00:02.500>you <00:03.000>up[00:03.500]"
+
+lyrics = llp.loads(lrc_text)
+line = lyrics[0]
+
+for word in line.content:
+    print(f"  [{word.start} -> {word.end}] {word.content!r}")
+    # [1000 -> 1500] 'Never '
+    # [1500 -> 2000] 'gonna '
+    # [2000 -> 2500] 'give '
+    # [2500 -> 3000] 'you '
+    # [3000 -> None] 'up'
+
+# 行级时间: line.start=1000, line.end=3500
+```
+
+### Reference Lines (Translation / Transliteration)
+
+LRC 文件中, 紧跟在带时间标签行后面的无标签行, 或与主行的时间戳相同的行, 会被解析为参考行, 常用于存放翻译或音译:
+
+```python
+lrc_text = """[00:01.000]Hello
+你好
+[00:02.000]World
+[00:02.000]世界
+"""
+
+lyrics = llp.loads(lrc_text)
+
+line = lyrics[0]
+print(line.text)                              # "Hello"
+print(line.reference_lines[0][0].content)     # "你好"
+```
+
+### Combining Lyrics
+
+将两份歌词 (如原文和翻译) 按时间标签合并:
+
+```python
+main = llp.loads("[00:01.000]Hello\n[00:02.000]World\n")
+translation = llp.loads("[00:01.000]你好\n[00:02.000]世界\n")
+
+# combine 方法: 翻译行挂到同时间点的 reference_lines 中
+combined = main.combine(translation)
+
+# 也可以用 + 运算符
+combined = main + translation
+
+for line in combined:
+    print(line.text)  # 主歌词
+    for ref in line.reference_lines:
+        ref_text = "".join(w.content for w in ref)
+        print(f"  -> {ref_text}")  # 参考行
+
+# other_as_refline_only=False 时, 翻译中找不到对应时间点的行会作为新行保留
+combined = main.combine(translation, other_as_refline_only=False)
+```
+
+### Implicit Line End
+
+当歌词行没有显式结束时间时, 可以自动用下一行的开始时间填充:
+
+```python
+lyrics = llp.loads(lrc_text, fill_implicit_line_end=True)
+
+# lyrics[0].end == lyrics[1].start
+```
+
+### Serialization Options
+
+`dumps` 支持以下选项:
+
+```python
+output = lyrics.dumps(
+    with_metadata=True,                 # 是否输出 metadata 段
+    use_bracket_for_byword_tag=False,   # 逐字标签使用 [...] 还是 <...> (默认) 
+    apply_offset_from_metadata=False,   # 是否读取并应用 metadata 中的 offset
+)
+```
+
+`apply_offset_from_metadata` 的行为: 正 offset 会让歌词显示提前 (`display_time = tag_time - offset`) . 如果应用 offset 会导致时间戳变负, 则只应用安全的部分, 剩余写回 `metadata["offset"]`.
+
+## References
+
+[LRC Wikipedia](https://en.wikipedia.org/wiki/LRC_(file_format))
+
+[SPL Specification](https://moriafly.com/standards/spl.html)
+
+## UwU?
+
+UwU!
+
+## License
+
+MIT License

lemony_lrc_parser-0.2.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+lemony_lrc_parser/__init__.py,sha256=9Uql8Fgt1FDNs3pIAGcKxLe9vqZbpyLCDxnmRiuD-Kg,2208
+lemony_lrc_parser/exceptions.py,sha256=hh9gPOkOYm7vSocAhirlswkx8rMU7CkIiLzEoxdxt4U,107
+lemony_lrc_parser/models.py,sha256=LdC9RxNL_ynWuM1MgnRJKQgOzOFjI7KF_xQfSPk1Vuk,6323
+lemony_lrc_parser/parser.py,sha256=ZJkiOCzx2eJQFK_D_5GBEVFFWoH5bFySXUZyFBZQ0s4,9877
+lemony_lrc_parser/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lemony_lrc_parser/regex.py,sha256=zGoNtcgVYN6RMb1cRs3dTZfr6I13hEnwEdsON9xvD1k,3918
+lemony_lrc_parser/serializer.py,sha256=Q-W3WrjXTaeIBj20Lp0BlfxCxf0O53mydEd_j-rHWHs,7004
+lemony_lrc_parser/timetag.py,sha256=rXmKl2NP9QNgxDvDGdvIBYK4I2HMysVq7U8O4nUs7A8,2772
+lemony_lrc_parser-0.2.1.dist-info/METADATA,sha256=hOxSZyhJHDLQC5eciQdAKbgNweqbHiB0TgbMU4-be3o,6076
+lemony_lrc_parser-0.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+lemony_lrc_parser-0.2.1.dist-info/licenses/LICENSE,sha256=Sn85iIuJalIesbHGlJTZ69jQMraRusqPCYNvmgJ1Rvo,1068
+lemony_lrc_parser-0.2.1.dist-info/RECORD,,

lemony_lrc_parser-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lemony_lrc_parser-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LemonekoUwU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.