功能说明
音乐源资料与刮削结果，优先使用哪一份？
歌曲信息、封面和歌词分别处理，可以来自不同地方。自动补全主要填补缺失内容；手动在单曲刮削预览中选择结果、勾选要替换的项目并应用，才会保存这些选择。仅查看预览不会改变现有资料。
Navidrome 等服务器曲库
以下以 iPhone 和 Mac 上的 Navidrome 为例。
| 内容 | 默认读取 | 普通／批量刮削 | 手动选择并成功应用 |
|---|---|---|---|
| 歌名、歌手、专辑、年份等 | 服务器返回的资料 | 只补缺失字段，保留已有值 | 使用勾选的新值，后续刷新保留用户修改 |
| 单曲封面 | 服务器提供的封面 | 不通过此流程补图或替换封面 | 使用已保存的新封面 |
| 歌词 | 先显示缓存，再核对服务器歌词；确认服务器没有歌词时才在线兜底 | 歌曲信息补全过程不替换服务器歌词 | Navidrome 的歌词保存为 Primuse 本地覆盖，服务器自动刷新不会换回旧歌词 |
Navidrome 的普通刮削流程即使是“重新刮削”，也仍只补空缺。要替换已有信息，需要进入单曲刮削预览，选择结果并应用。
例如，Navidrome 的专辑名是 A：自动补全不会把它改成在线找到的 B；手动在预览中勾选专辑名 B 并应用后，Primuse 使用 B，重新扫描会保留这次修改。没有手动覆盖的歌曲信息仍会跟随服务器的有效更新。
Jellyfin、Emby、Plex、Subsonic 家族、飞牛音乐等服务器曲库，歌曲信息同样以服务器资料为基础。歌词能否写回服务器取决于各来源的能力，Navidrome 的本地保存方式不代表所有服务器的保存方式。
本地、NAS 和网盘等文件源
本地文件、WebDAV、SMB、FTP 和网盘等来源，通常按以下顺序读取：
- 歌曲信息：先读音频内嵌标签，缺失信息再按条件在线补全；没有有效标题时使用文件名等显示回退。
- 单曲封面：内嵌封面 → 可用的同目录封面 → 在线补全。实际显示时会先使用已保存的缓存，成功应用的新封面也从这里显示。
- 歌词：可用的同目录歌词文件 → 内嵌歌词 → 在线兜底。用户选定的歌词文件和已经保存的本地修改另有保护。
手动重新刮削并成功应用后，Primuse 使用已应用的结果。用户修改过的标签会保留，避免后续读取文件标签时恢复旧值。是否同时修改音频文件、同目录文件或服务器，需要看该来源的写回能力与设置；在 Primuse 中应用成功，不等于所有来源都已同步修改。
为什么先看到缓存，稍后歌词又更新了？
缓存用于尽快显示和离线使用。缓存命中本身不代表内容被永久固定。
服务器歌词会在后台按条件重新核对。自动在线兜底得到的歌词也可能参与后续更新；手动保存为本地覆盖的歌词不会被服务器自动刷新替换。
常规自动缓存更新会保护歌词精度，避免把已有逐字歌词降成逐行歌词。手动改选歌词、原歌词文件被删除后的回退等情况另按对应操作处理。文件源核对同目录歌词时，还会考虑用户是否选定该文件、当前引用和时间轴精度。
多个在线刮削源之间怎么选？
只使用设置中已启用、且支持对应内容的来源，按用户设置的顺序查询。
- 歌曲信息：检查匹配程度和资料完整性；前面的可信结果不够完整时，继续查询后面的来源。
- 封面：使用按顺序取得的首个匹配且能下载的结果。
- 歌词：拿到逐字歌词后停止；如果先取得的不是逐字歌词，最多再查询后面两个歌词源，保留时间轴更细的结果，同精度保留先取得的结果。
Apple TV 的差异
Apple TV 的服务端曲库在缺少封面时，允许通过在线刮削补图；iPhone 和 Mac 的普通服务端刮削不补封面。上面的 Navidrome 歌词刷新与本地覆盖说明以 iPhone、Mac 实现为准。
功能记录
Apple TV 端补全音乐源管理、直连播放、本机扫描元数据、搜索、歌词和多语言界面
云盘刮削结果可回写 OneDrive、Dropbox、Google Drive、百度网盘和阿里云盘
功能迭代
- 1.12.3新增
标签与元数据刮削 · 1.12.3
查看原始更新日志- 搜索新增分类标签视图并精简歌曲分组
- 记住单曲刮削内容并独立选择替换结果
- 1.12.2调整
标签与元数据刮削 · 1.12.2
查看原始更新日志- 补全标签不再反复重读同一批歌
- 整轨 CUE 专辑补全标签时各分轨共用一次读取
- 网盘、NAS 刚扫进来的歌等读完标签再在线补全，不再按同名的别人的歌配封面
- 重扫后写回标签、封面和歌词不再一直误报源文件已变化
- 1.12.1调整
标签与元数据刮削 · 1.12.1
查看原始更新日志- 删掉又恢复的音乐源照样能接过别的设备读好的标签
- 播客订阅的节目可以像电台一样归进文件夹、贴上标签，按文件夹和标签筛选 (#325)
- 从搜索结果点进专辑、艺人后多选歌曲，标签栏和迷你播放条会让开，不再压住底部的批量操作栏 (#304)
- Navidrome 等 Subsonic 源按服务端的专辑来分组：服务端按专辑名并成一张、各首又没有专辑艺术家标签的原声带与合辑，不再按曲目艺术家拆成每首一张 (#333)
- 刮削到的封面存不下时不再给歌曲记上封面，这类歌曲不会一直显示默认封面、刮削缺失也不再跳过它们
- 同名专辑里的合唱和 feat. 歌曲并进主唱那张：没写专辑艺人标签时，《纵横四海》里「李荣浩 & 张惠妹」那首不再自成一张；年份不同或曲号撞车的同名专辑照样分开，写了专辑艺人标签的仍按标签分，手机、Mac、电视都生效 (#338)
- 刮削搜索词测试跟上保留 Live 等版本标记的写法
- 全屏效果里缺标签的歌不再显示演示用的艺人和专辑
- FLAC、Ogg、APE 标签和自建歌词服务里的 GBK/Big5 歌词能读出来
- 导入或读取标签时退到后台，不再反复重画看不见的界面，后台耗电和发热更少
- 1.12.0调整
标签与元数据刮削 · 1.12.0
查看原始更新日志- 读标签和扫描时其他页面滑动更顺：每首歌的读取与合并、扫描新歌的整理都挪到后台
- 在线歌词会挑时间轴更细的那份，歌词 API 服务返回的单行 TTML 和逐字歌词能直接用，自定义刮削源可以从文件导入 (#317)
- 补读标签时歌曲列表不再每隔几秒整页重画，每一行只在自己那首的读取状态变了时才更新
- Mac 的歌曲表格和歌单表格在后台写回标签时只重建内容变了的行，右键菜单也不再跟着整张表一起重建
- 歌手页在后台读标签、刮削时不再反复重算歌曲列表、热门排行和播放次数
- 后台读标签、扫描入库时不再每批都把所有歌单成员整遍核对一次，只在真可能删掉成员时才核对
- 1.11.5调整
标签与元数据刮削 · 1.11.5
查看原始更新日志- 有声书排在音乐后面读标签
- 同一账号的 iPhone、iPad、Mac 共用读好的歌曲标签
- 重新扫描文件夹时保留已读出的标签，只有换过的文件才重新读
- 有声书详情页开着时读出第一集的标签，页面跟着这本书走，不再变空
- 手改的标签、换的封面和评分评论在 iPhone、iPad、Mac 之间同步
- 扫描认出文件挪动、标签编辑写回出错时也按资料库里最新的那一行处理
- 滑动列表时补读到的标签和扫描结果先攒着，停稳后再一次写进资料库
- 有声书读出标签换了书的 id 后，倍速、归档、收藏、书架顺序、首页挑的书和保持离线跟着这本书走
- 扫描和读取标签时，其他页面滑动不再被后台整理资料库打断
- 1.11.4调整
标签与元数据刮削 · 1.11.4
查看原始更新日志- 云盘写回标签、歌词、封面时也遵守这个账号的限流冷却，批量改标签不再在冷却中一直往上传 (#232)
- 重新读取标签、卡拉OK 分离和写回标签时从音乐源整首下载的文件用完即删，不再一直占用手机空间
- 音频解码与标签读写组件 SFBAudioEngine 升级到 0.14.0
- 1.11.3调整
标签与元数据刮削 · 1.11.3
查看原始更新日志- 半小时以上的 m4a/m4b 有声书单集也能读出标签 (#178)
- 1.11.2调整
标签与元数据刮削 · 1.11.2
查看原始更新日志- 播放页的音质与来源改成进度条下方的标签，轻点可查看完整音频信息
- 1.11.1调整
标签与元数据刮削 · 1.11.1
查看原始更新日志- 刮削后的歌曲信息重开 App 不再变回文件里的旧值
- 刮削只写勾选的部分，CUE 分轨的曲目信息不再被覆盖
- 专辑和歌曲可以一键恢复成音乐文件里的标签
- 智能整理标签可以用内置 AI 批量修正曲名、艺人和专辑里的乱码与不规范写法
- 智能整理标签没开发送授权时可以一键打开，新设备默认允许向智能服务发送内容
- Apple TV 专辑页可以一键恢复成音乐文件里的标签
- 修正云盘标签测试的队列初始化
- 1.10.2调整
标签与元数据刮削 · 1.10.2
查看原始更新日志- Apple TV 支持刮削：可以匹配歌曲信息、补全整张专辑与自动获取在线歌词，封面不再配错
- 扫码传到 Apple TV 时可以一并同步刮削、歌词 API 服务和智能功能等设置
- 同步歌词与电视刮削的工程文件引用
- Mac 侧栏资料库按外观设置里的顺序与开关显示，设置页可拖动排序，电台页标签条下不再留大片空白
- Apple TV 可以直接导入自定义刮削源
- 百度网盘上刮削或编辑歌词不再误报写回失败
- 1.10.1修复
标签与元数据刮削 · 1.10.1
查看原始更新日志- 标签建议与批量编辑 —— 编辑标签时给出修改建议，可一键检查整个曲库，也能一次编辑多首歌；播放时按情况给出智能提示
- 飞牛音乐 —— 歌词优先选能解析的候选并沿用服务端校准的偏移，手机、Mac 与 Apple TV 一致；标签写回可改专辑名、自动创建流派、上传封面；歌单清单一次读取
- 标签 —— 修复 m4a 的音轨号与碟号读不出、写回时覆盖没改动的字段，以及下载工具给重名文件加的「(1)」让歌名显示成歌手名
- 1.9.8修复
标签与元数据刮削 · 1.9.8
查看原始更新日志- 自定义歌词服务器 —— 刮削支持自填歌词 API 服务器，找不到歌词时可自动在线获取
- 标签读取调度 —— 新增歌曲优先读取标签，WebDAV 与 NAS 读取进一步提速；桌面端按设备能力使用最快档位
- 歌词编辑 —— 写入权限检查不再卡住，编辑带分组标签的 M4A 时保留原有内嵌歌词
- 音乐源 —— 修复协议选项与地址不同步导致连接失败、群晖密码编辑与失效后的认证、取消勾选目录后歌曲仍留在资料库、123 云盘合并未完成时标签写回误报失败
- 音乐源与首页 —— 加快 WebDAV/NAS 标签读取和大量电台的资料库呈现，首页音乐/电台切换更流畅
- 1.9.7调整
标签与元数据刮削 · 1.9.7
查看原始更新日志- 电台文件夹、标签与订阅 —— 电台可按文件夹和标签整理，支持清单分组导入、清单 URL 订阅、图片链接与 SVG 台标 (#118 #119)
- 标签读取自动降速 —— 服务端返回 5xx 时自动放慢读取节奏，WebDAV 的请求与响应会记录下来便于排查
- 服务器增量同步 —— 媒体服务器与 Subsonic 系大曲库边扫边入库、断点续扫，并同步服务端标签、封面、评分与删除
- 1.9.6修复
标签与元数据刮削 · 1.9.6
查看原始更新日志- 本版本让 Apple TV 可以直接添加几乎所有类型的音乐源并播放 Apple Music，首页与 CarPlay 支持就地可视化编辑，沉浸画面全面升级，并系统性解决大曲库扫描、标签读取发热与多处并发问题。
- 电台台标与实时元数据 —— 自动解析电台台标来源并在播放中显示实时元数据，批量添加时展示台标，也可以手动获取
- 标签读取档位 —— 设备发热后读取档位继续生效，并新增暂停档
- 标签检查详情 —— 重做详情页排版，统一卡片样式并加入状态分布条
- 标签读取节奏 —— 全速读取前以醒目样式提示风险，播放期间多给一个读取位，定期记录实测速率与当时的限制条件；系统收回后台时间不再显示为读取失败；重新读取全部标签改为直接执行，单个音乐源移到长按菜单
- 重复歌曲清理 —— 不再删除 WebDAV 源文件，标签不足的同名歌曲也不会被误清理
- 标签乱码 —— 修复专辑标签乱码、截断乱码与艺人字段串入，部分元数据回填一并修正
- 并发问题 —— 修复资料库索引重建被丢弃、回填补丁互相覆盖与持久化饥饿，后台元数据恢复与流式缓存冲突，音乐源后台任务登记与缓存清理的竞态
- macOS 小组件 —— 修复封面撑破布局，暂停时标签改为已暂停
- 1.9.5新增
标签与元数据刮削 · 1.9.5
查看原始更新日志- 本版本加入局域网设备互传与网页管理，本地音乐可在文件 App 中访问，新增 Songloft 音乐源与九种语言，并大幅加快标签读取。
- Apple TV 整批标签重读 —— Apple TV 上可以整批重读标签
- 标签读取加速 —— SMB 标签读取显著提速并支持后台持续处理，速度档位可调，全速模式加入保护、冷却与任务恢复，错误反馈更明确
- WebDAV 标签回填 —— 播放 WebDAV 歌曲时按需回填文件标签
- 标签读取异常 —— 隔离读取异常并降低详情页开销，切换档位后的速度显示一并修正
- 标签读取调度 —— 高性能读取入口移到音乐源，并按设备性能自适应调整，电视端队列一并优化
- 1.9.4修复
标签与元数据刮削 · 1.9.4
查看原始更新日志- 本地扫描与回填 —— 优化本地音乐扫描与元数据回填，降低来源同步状态的重复写入
- 批量操作栏 —— 修复批量操作栏被标签栏遮挡
- Apple TV —— 修复顶部标签焦点跳转、播放恢复与 Subsonic 歌词加载
- 其他 —— 修复媒体服务器资料库的目录分类、首页电台封面加载、道理鱼播放未保留原始音频，以及刮削搜索里露出来源内部标识
- WebDAV 扫描 —— 降低扫描负载，标签详情页一并提速
- 1.9.3修复
标签与元数据刮削 · 1.9.3
查看原始更新日志- 多格式标签读取 —— 扩展支持的文件格式，并补上读取诊断
- 后台标签补全 —— 限制单次补全的负载，避免长时间占用
- 标签检查详情 —— 重做移动端布局，精简信息层级，并区分「尚未完整检查」的状态
- 歌词语言与翻译 —— 修复语言误判导致翻译弹框反复阻塞，无语言标签的歌词按正确方向排版
- 标签读取 —— 修复云盘扫描后标签回填没有启动、本地标签读取失败没有反馈、云端重读把有效音频误判为无效，以及后台读取导致的发热
- 1.9.2修复
标签与元数据刮削 · 1.9.2
查看原始更新日志- WebDAV 标签回写 —— 音频标签与封面可以写回 WebDAV 来源
- 其他 —— 修复写权限预检无法结束、重复歌曲清理的选择与删除保护、高保真输出采样率异常、来源恢复后标签回填不再重试，以及 iPad 上播放器遮挡内容与封面选择器立即关闭
- 大资料库 —— 缩短冷启动耗时，减少元数据解析争用，改善前台运行与前后台切换的卡顿
- 1.9.1修复
标签与元数据刮削 · 1.9.1
查看原始更新日志- 歌词打轴保存 —— 修复刮削来的歌词重新打轴后无法保存
- 云盘扫描回填 —— 加固云盘扫描与元数据回填
- 1.9.0改进
标签与元数据刮削 · 1.9.0
查看原始更新日志- 播放缓冲与专辑刮削 —— 优化缓冲管理，专辑详情页可直接刮削
- 重复读取标签 —— 服务端曲库不再重复读取同一首歌的标签
- 1.8.1修复
标签与元数据刮削 · 1.8.1
查看原始更新日志- 本版本新增道理鱼与飞牛音乐两个音乐源，改进刮削候选的排序与准确性提示，并修复群晖播放、凭据保存和跨端同步的多个问题。
- 刮削候选排序 —— 手动刮削的候选按时长和匹配度重新排序，并给出准确性提示
- 远端标签读取 —— 远端标签改为在内存中解析，减少落盘与重复下载
- 群晖播放 —— 修复中断后 DTS 无法恢复、下一首预缓存失效与 DTS 时长错误，元数据与队列推进一并稳定
- 刮削写回 —— 只读来源不再尝试写回刮削结果
- NAS 元数据刷新 —— 刷新 NAS 元数据并如实报告结果
- 自动刮削匹配 —— 修复结构化文件名的自动匹配
- 歌词定位 —— 修复刮削完成后当前歌词的定位
- 大文件标签 —— 修复超大 ID3 标签与 moov 在文件尾的音频读取失败
- 歌单批量刮削 —— 补上批量刮削的进度与结果反馈
- 1.8.0修复
标签与元数据刮削 · 1.8.0
查看原始更新日志- 正在播放的刮削与歌词 —— 统一刮削入口，歌词显示一并调整
- Apple Music 队列 —— 修复队列无法自动推进，混合队列与手动刮削结果不再丢失，刮削歌词时保留官方封面
- 高保真混音器 —— 修复高保真音频图模式下的混音器冲突与元数据读取
- 标签栏 —— 没有播放内容时标签栏不再消失
- 刮削占位端点 —— 跳过没有实际内容的刮削服务地址，减少无效请求
- 1.7.3修复
标签与元数据刮削 · 1.7.3
查看原始更新日志- Apple Music 歌词刮削 —— 播放器折叠后任务仍由服务层继续执行，并统一使用规范歌曲身份保存歌词
- 音乐源扫描流程 —— 引入目录选择会话，合并扫描变更和检查点写入，改善 FTP 连续性及远端元数据解析
- 搜索结果播放崩溃 —— 保持标签页与底部播放器的视图结构稳定，修复关闭搜索控制器时的并发崩溃
- CloudKit 与 SMB 崩溃 —— 缺少 CloudKit 权限时安全停用同步；串行化 SMB 会话生命周期，避免批量刮削写回与断开连接竞态导致闪退
- 批量刮削准确性 —— 远端文件使用稳定身份种子与置信匹配，重复副本保持一致；阻止重叠批次，并在只读或凭据失效来源上停止重复写回
- 大型曲库卡顿 —— 修复冷启动、歌曲列表刷新、后台刮削和大批量清理引发的界面停顿与系统 watchdog 退出
- 刮削与翻译日志 —— 空标题不再请求在线提供方；歌词已是目标语言时不再触发无意义翻译和失败缓存
- 前台批量任务 —— 仅在应用真正进入后台时申请有限后台执行窗口，消除长时间前台刮削产生的系统后台任务告警
- 1.7.2调整
标签与元数据刮削 · 1.7.2
查看原始更新日志- 大型曲库任务 —— 歌曲列表刷新、批量清理和后台刮削改为分批处理，降低前台停顿
- 1.7.1改进
标签与元数据刮削 · 1.7.1
查看原始更新日志- 音乐源管理 —— 优化来源状态管理和远端元数据解析，目录选择使用独立会话后再触发扫描
- 1.7.0修复
标签与元数据刮削 · 1.7.0
查看原始更新日志- 首次安装功能导览 —— 介绍云盘、NAS、Apple Music、元数据刮削、跨设备播放、App 图标和首页排版等核心能力
- 歌曲标题 —— 扫描和标签回填优先采用音频内嵌标题，不再始终显示文件名
- tvOS 导航与播放控制 —— 修复筛选焦点、返回标签栏、全局播放暂停及远程命令的主线程问题
- 扫描与标签读取 —— 批量提交曲库变更、降低进度发布与检查点写入频率，并将大型 JSON 编码移出主线程
- 1.6.4改进
标签与元数据刮削 · 1.6.4
查看原始更新日志- 为 Jellyfin、Emby、Plex 增加服务器基础路径、服务器端元数据刷新和刮削结果回写
- 优化刮削源导入和云存储连接流程
- 1.6.2修复
标签与元数据刮削 · 1.6.2
查看原始更新日志- 重做音乐源软删除、缓存清理和元数据回填失败重试
- 修复 CarPlay 崩溃与卡顿、音频路由崩溃和标签栏超限
- 修复 Plex/Subsonic 扫描中断、Synology 重扫丢元数据、百度令牌编码和缓存文件名碰撞
- 1.6.1调整
标签与元数据刮削 · 1.6.1
查看原始更新日志- Apple TV 端补全音乐源管理、直连播放、本机扫描元数据、搜索、歌词和多语言界面
- 云盘刮削结果可回写 OneDrive、Dropbox、Google Drive、百度网盘和阿里云盘