跳转至

使用指南

Lyra 的页面按「看内容、修内容、管理系统」分成三组。第一次使用建议按下面的顺序走一遍。

第一次使用

  1. 只读审计。 保持 read_only = true，打开「音乐」和「文件」，确认曲库规模、格式、歌词状态符合预期。
  2. 看概览。 确认受管根健康、标签覆盖率、歌词覆盖率和问题分布。
  3. 小批量试跑。 在「歌词刮削」里选一个目录，限制数量，先抓取不写入。
  4. 审查。 在「歌词审查」逐首确认来源、行数和时间轴。
  5. 开启写入。 确认配置和备份目录后，再打开写入开关。
  6. 处理标签。 在「标签刮削」先扫描，处理「推荐采纳」和「待审查」。
  7. 整理目录。 在「曲库整理」先预览，确认新路径后再执行。
  8. 重复音频。 先检测，按分类查看，最后人工确认删除。

概览

概览页展示曲库规模、时长、专辑/艺人数、歌词覆盖率、标签完整度、流派和时长分布，以及待处理入口。

  • 「重新统计」会强制重新扫描；首次统计在 NAS 上可能需要几秒到几十秒。
  • 「写入进度」只统计最近 60 天。
  • 「待处理」里的数字可以点进对应页面。
  • 侧栏底部的「监控运行中 / 监控无心跳」来自监控进程的心跳。只运行 Web 不运行 lyra watch 时显示无心跳是正常的。

音乐

按路径搜索，按问题、歌词状态和来源过滤。每一行显示歌词文件状态、内嵌歌词状态和问题标签。

  • 点问题标签进入修复面板。
  • 「详情」查看标签、歌词、封面和文件信息。
  • 支持分页，默认每页 50 首。
  • 问题码包括缺歌词、缺内嵌、缺 .lrc、歌词名不符、容器与扩展名不符、缺封面、缺 MBID 等。

文件

按文件类型浏览音频、歌词、图片和文本。可以多选后移入回收站。

  • 删除是移动，不是 unlink。
  • 音频删除时，同名 .lrc 会一起移走。
  • 图片、歌词和文本可以预览。
  • 不建议在这里整理目录；目录整理用「曲库整理」，因为它有预览和撤销。

歌词审查

三个标签页：

  • 推荐采纳：所有硬性条件通过，只是分数没有达到自动接受线。可以批量或逐首采用。
  • 待审查：需要人工确认。可以对比来源、看逐行差异、播放音频。
  • 无音源：没有对应音频的歌词文件，通常是放错目录或改名残留。

写入前会显示将写入的字段、来源和差异。人工确认的写入默认做完整备份。

歌词刮削

选择范围和数量，抓取歌词到暂存区。抓取本身不写音乐文件。

  • 「立即写入」把暂存歌词写入音频和 .lrc。
  • 任务在后台执行，可以离开页面；进度和心跳会显示。
  • 自动监控也会按间隔执行同样的流程。
  • 已有有效同步歌词默认跳过，不会反复覆盖。

标签刮削

标签页按「推荐采纳 / 待审查 / 未匹配」分组。

  • 扫描会先检查 MusicBrainz 是否可用；不可用时不会把全库标成未匹配。
  • 每首曲目显示逐字段对照：本地值、来源值、判断。
  • 「可补」只补空字段；「纠正」按同目录专辑统一发行字段；「冲突」需要人工确认。
  • 冲突字段默认勾选，支持全选和取消全选。
  • 写入前有确认框，列出字段和影响。
  • 写入历史可以按字段撤销。

详见标签刮削。

曲库整理

三个标签页：

一键整理

选择受管根、要整理的目录（可多选）和要排除的目录（可多选），生成预览。

  • 预览列出每首歌的旧路径、新路径、状态和原因。
  • 状态包括移动、已正确、目标冲突、无法生成路径。
  • 目标已存在的文件不会覆盖，会标成冲突。
  • 移动后为空的目录会列出来，默认勾选清理。
  • 只有点击「执行」才会真正移动。

命名规则和重复处理见曲库整理。

重复音频

按证据分为三类：

分类 判定 处理建议
音频完全一致 去掉标签后的音频哈希相同 通常可以直接保留一份
同一录音 MusicBrainz 录音 ID 或 AcoustID 指纹相同 可能是不同压缩或版本，试听后决定
标题/艺人/时长相近 标题、艺人相同，整组时长跨度不超过 2 秒 不一定同一录音，必须试听

每张卡片显示格式、时长、大小、标题、艺人、专辑、路径和保留理由。建议删除的副本默认不勾选；可以逐项选择、全选当前分类，或按分类一键删除。

参照项标为「其他分类保留」，不参与删除。删除前会再次确认分类和数量。

空目录

扫描曲库中的空目录，预览后移入回收站。刚被填入文件的目录不会被当成空目录。

回收站

按批次查看移入回收站的文件。可以还原或永久删除。

  • 还原会保留原相对路径。
  • 永久删除不可恢复。
  • 回收站位于 data/trash/，不会自动清理。

日志

三个标签页：

  • 写入：歌词和标签写入记录，可以按字段撤销。
  • 改名：文件改名记录，可以逐条撤销。
  • 整理：移动、删除和空目录清理记录，支持多选批量撤销。

撤销按时间倒序执行。单条失败不会阻止其他条目，失败原因会显示在结果里。

设置

  • 账户：登录状态、退出登录。
  • 外观：深色/浅色，跟随系统。
  • 标签刮削：自动扫描、间隔、自动写入、指纹、单轮上限、时长容差。
  • 修改密码：至少 10 位。
  • API 令牌：给脚本和移动端签发 Bearer Token，明文只显示一次。
  • 运行信息：版本、数据库结构、写入开关、来源和受管根。

设置页保存的标签策略会写入数据库，并覆盖配置文件里的 [policy.tags]。监控进程每分钟检查一次变更。

键盘与移动端

界面在桌面和手机上使用同一套路由。手机上侧栏变成抽屉，表格变成卡片列表，操作按钮保留在卡片内。歌词对比和整理预览在窄屏下改为纵向排列。