Primuse 全链路串联指南与核心设计逻辑（为什么这么做）

功能说明

一、六个步骤把 Primuse 全套功能串起来用

1. 选对音乐源入口：按协议选，而不是只看设备品牌

已有媒体服务器（推荐，同步最快）：如果你已经搭建了 Navidrome、Subsonic、Jellyfin、Emby、Plex、Audiobookshelf、Ting Reader、飞牛音乐或群晖 Audio Station，请直接添加对应的服务器类型。服务器已在后台建好索引，几万首歌只需几十秒即可同步完目录与歌单。
NAS 共享文件夹与网盘：支持群晖 File Station、威联通、SMB、WebDAV、SFTP、FTP、NFS、S3，以及百度网盘、阿里云盘、OneDrive、Google Drive、Dropbox、123 云盘、光鸭云盘、pCloud、Drime、InfiniCLOUD、115 网盘。添加时先勾选放音乐的文件夹；如果某个目录放的是评书、相声或 MP3 有声书，直接在选目录时标为**「有声」**，它们会自动进入「有声书」书架，不会混进音乐列表。
本机音乐与 Apple Music：导入本机文件时选**「引用文件夹」**即可免复制直接播放；开启 Apple Music 授权后，可将订阅歌曲与你自己的 NAS、网盘无损曲库放进同一个队列混合播放。
家用 NAS 内外网双地址：在同一个音乐源里同时填好局域网地址和外网域名，在家连 Wi-Fi 走内网满速直连，出门自动切外网，歌单、红心和统计完全共用。

2. 扫描与整理：先列目录开播，再后台补齐标签与 CUE / ISO 分轨

WebDAV、SMB 和网盘采用两阶段扫描：第一阶段先快速列出音频文件让你马上能点播；第二阶段在后台读取内嵌标签、封面、同目录歌词，以及 .cue、SACD ISO、DVD-Audio ISO、数据光盘 ISO 的分轨信息。
网盘默认开启**「仅在 Wi-Fi 下加载云盘详情」**以节省移动流量，连上 Wi-Fi 后会自动继续补齐歌手与专辑信息。

3. 封面、歌词与简介补全：自动填空与单曲手动覆盖

在「设置 → 元数据与刮削」开启内置刮削源（支持 Apple Music 目录、Last.fm 歌手与专辑简介、AMLL 逐字歌词库或自定义歌词 API）。
自动/批量刮削只填补空白字段，绝不篡改你在服务器或文件里已有的专辑名与封面；如果你想替换某首歌现有的错误资料，打开这首歌的**「单曲刮削预览」**勾选并应用，Primuse 会把它作为本地高优先级覆盖永久保留。

4. 播放、串烧与两条音频输出链路

「音效处理」模式：适合日常耳机、蓝牙与车载收听。支持 10 段均衡器（可按蓝牙耳机/音箱自动切换预设）、空间混响、ReplayGain 回放增益（自动平衡不同专辑的音量并在音质栏显示生效 dB）、升降调、倍速、智能/固定淡入淡出，以及只播每首歌高潮段的**「音乐串烧」**。
「高保真直通」模式：适合外接 USB DAC 听无损。音频流原样直通，在 Mac 上支持独占输出并根据每首歌的原始采样率自动切换硬件采样率。

5. 边听边缓存 vs 固定离线下载 vs 局域网缓存同步

音频缓存：边听边存并预取下一首，受「音频缓存上限」自动淘汰管理；支持在「音乐源 → 目录」中一键**「缓存所选目录」**并通过三行进度条查看实时速度与剩余时间。
离线下载：手动点下载或开启歌单/有声书「始终保持离线」的内容独立存放，不受缓存上限清理影响；支持保留原文件或转码为 128 / 192 / 256 / 320 kbps AAC 节省手机存储空间。
缓存同步：Mac 上已有大量缓存时，在同一 Wi-Fi 下打开「存储管理 → 缓存同步」，直接走局域网把音频缓存传给 iPhone，免去重复从网盘下载。

6. 歌词、实况照片分享与本机 AI 卡拉 OK

支持在**「在线歌词」与「内嵌/同目录歌词」之间一键切换**，开启本机离线翻译、Apple Intelligence 或自备翻译源实现双语歌词，并为日/韩/粤/中自动加注罗马音或假名。
歌词分享卡片支持开启**「附带音乐」**，直接导出带原声与动态歌词的 iPhone 实况照片（Live Photo） 或高清视频。
点开麦克风进入卡拉 OK 舞台，完全依靠本机神经网络实时分离伴奏与人声，支持升降调、麦克风耳返混响，分离完成后还能将纯伴奏或纯人声导出为 WAV / M4A。

二、为什么这么设计？（常见疑问背后的底层逻辑）

为什么 SMB / WebDAV 某次扫描少了一大批歌时，不立即把它们从曲库删掉？ 家用 NAS 硬盘休眠唤醒慢、外网反代偶发超时或云盘限流时，很容易在某次请求里漏返回目录。如果一没扫到就立刻删歌，你的本地歌单、评分、听歌次数和离线绑定就会被误清空。因此 Primuse 设有骤减保护與连续扫描确认机制；若确认是自己删了文件，可在音乐源菜单的「服务端删掉的歌」里手动点「立即移除」。
为什么开启「高保真直通」或播放 Apple Music 在线歌曲时，均衡器（EQ）、淡入淡出和回放增益不生效？ 高保真直通（Bit-perfect）的目标是让送到解码器的每一个采样点与源文件分毫不差，任何 EQ、淡入淡出混音、变调或增益都会改写 PCM 采样，因此直通模式会故意绕过整条音效链；而 Apple Music 订阅流受系统 DRM 保护，由系统通道直接输出，不允许第三方 App 截取原始音频流做音效处理或频谱分析。
为什么切到手机后台后，即使音乐还在播放，大曲库扫描也可能会暂停？ iOS 对后台进程的 CPU 与磁盘读写有严格的看门狗限制。如果后台边放歌边全速拉取几万首文件头和解压封面，系统会直接强杀进程导致音乐中断。因此切后台时 Primuse 会主动保存检查点（Checkpoint）并暂停重度扫描，切回前台立刻从断点接着扫。
为什么开了「与其他 App 同时播放」后，锁屏和耳机按键不能切歌？ 这是 iOS 音频会话的系统规则：开启混音模式（允许边玩游戏/看视频边听歌）后，系统不再把该 App 作为独占的「正在播放」控制对象。日常需要用锁屏、控制中心或耳机按键控制时，关闭「与其他 App 同时播放」即可恢复。
为什么「离线缓存音质」选了 AAC 转码，下载那一下还是消耗原文件流量？ 网盘（百度网盘、OneDrive 等）和 SMB/WebDAV 没有服务端转码能力，只能下发原文件，由手机芯片在本地转成 256k AAC 来节省 70% 以上的手机闪存空间。如果你用的是 Navidrome / Jellyfin / Emby 并想省移动流量，请在「播放设置 → 传输音质」中设置移动网络转码码率，由服务器转好再发给手机。

功能说明

一、六个步骤把 Primuse 全套功能串起来用

1. 选对音乐源入口：按协议选，而不是只看设备品牌

已有媒体服务器（推荐，同步最快）：如果你已经搭建了 Navidrome、Subsonic、Jellyfin、Emby、Plex、Audiobookshelf、Ting Reader、飞牛音乐或群晖 Audio Station，请直接添加对应的服务器类型。服务器已在后台建好索引，几万首歌只需几十秒即可同步完目录与歌单。
NAS 共享文件夹与网盘：支持群晖 File Station、威联通、SMB、WebDAV、SFTP、FTP、NFS、S3，以及百度网盘、阿里云盘、OneDrive、Google Drive、Dropbox、123 云盘、光鸭云盘、pCloud、Drime、InfiniCLOUD、115 网盘。添加时先勾选放音乐的文件夹；如果某个目录放的是评书、相声或 MP3 有声书，直接在选目录时标为**「有声」**，它们会自动进入「有声书」书架，不会混进音乐列表。
本机音乐与 Apple Music：导入本机文件时选**「引用文件夹」**即可免复制直接播放；开启 Apple Music 授权后，可将订阅歌曲与你自己的 NAS、网盘无损曲库放进同一个队列混合播放。
家用 NAS 内外网双地址：在同一个音乐源里同时填好局域网地址和外网域名，在家连 Wi-Fi 走内网满速直连，出门自动切外网，歌单、红心和统计完全共用。

2. 扫描与整理：先列目录开播，再后台补齐标签与 CUE / ISO 分轨

WebDAV、SMB 和网盘采用两阶段扫描：第一阶段先快速列出音频文件让你马上能点播；第二阶段在后台读取内嵌标签、封面、同目录歌词，以及 .cue、SACD ISO、DVD-Audio ISO、数据光盘 ISO 的分轨信息。
网盘默认开启**「仅在 Wi-Fi 下加载云盘详情」**以节省移动流量，连上 Wi-Fi 后会自动继续补齐歌手与专辑信息。

3. 封面、歌词与简介补全：自动填空与单曲手动覆盖

在「设置 → 元数据与刮削」开启内置刮削源（支持 Apple Music 目录、Last.fm 歌手与专辑简介、AMLL 逐字歌词库或自定义歌词 API）。
自动/批量刮削只填补空白字段，绝不篡改你在服务器或文件里已有的专辑名与封面；如果你想替换某首歌现有的错误资料，打开这首歌的**「单曲刮削预览」**勾选并应用，Primuse 会把它作为本地高优先级覆盖永久保留。

4. 播放、串烧与两条音频输出链路

「音效处理」模式：适合日常耳机、蓝牙与车载收听。支持 10 段均衡器（可按蓝牙耳机/音箱自动切换预设）、空间混响、ReplayGain 回放增益（自动平衡不同专辑的音量并在音质栏显示生效 dB）、升降调、倍速、智能/固定淡入淡出，以及只播每首歌高潮段的**「音乐串烧」**。
「高保真直通」模式：适合外接 USB DAC 听无损。音频流原样直通，在 Mac 上支持独占输出并根据每首歌的原始采样率自动切换硬件采样率。

5. 边听边缓存 vs 固定离线下载 vs 局域网缓存同步

音频缓存：边听边存并预取下一首，受「音频缓存上限」自动淘汰管理；支持在「音乐源 → 目录」中一键**「缓存所选目录」**并通过三行进度条查看实时速度与剩余时间。
离线下载：手动点下载或开启歌单/有声书「始终保持离线」的内容独立存放，不受缓存上限清理影响；支持保留原文件或转码为 128 / 192 / 256 / 320 kbps AAC 节省手机存储空间。
缓存同步：Mac 上已有大量缓存时，在同一 Wi-Fi 下打开「存储管理 → 缓存同步」，直接走局域网把音频缓存传给 iPhone，免去重复从网盘下载。

6. 歌词、实况照片分享与本机 AI 卡拉 OK

支持在**「在线歌词」与「内嵌/同目录歌词」之间一键切换**，开启本机离线翻译、Apple Intelligence 或自备翻译源实现双语歌词，并为日/韩/粤/中自动加注罗马音或假名。
歌词分享卡片支持开启**「附带音乐」**，直接导出带原声与动态歌词的 iPhone 实况照片（Live Photo） 或高清视频。
点开麦克风进入卡拉 OK 舞台，完全依靠本机神经网络实时分离伴奏与人声，支持升降调、麦克风耳返混响，分离完成后还能将纯伴奏或纯人声导出为 WAV / M4A。

二、为什么这么设计？（常见疑问背后的底层逻辑）

为什么 SMB / WebDAV 某次扫描少了一大批歌时，不立即把它们从曲库删掉？ 家用 NAS 硬盘休眠唤醒慢、外网反代偶发超时或云盘限流时，很容易在某次请求里漏返回目录。如果一没扫到就立刻删歌，你的本地歌单、评分、听歌次数和离线绑定就会被误清空。因此 Primuse 设有骤减保护與连续扫描确认机制；若确认是自己删了文件，可在音乐源菜单的「服务端删掉的歌」里手动点「立即移除」。
为什么开启「高保真直通」或播放 Apple Music 在线歌曲时，均衡器（EQ）、淡入淡出和回放增益不生效？ 高保真直通（Bit-perfect）的目标是让送到解码器的每一个采样点与源文件分毫不差，任何 EQ、淡入淡出混音、变调或增益都会改写 PCM 采样，因此直通模式会故意绕过整条音效链；而 Apple Music 订阅流受系统 DRM 保护，由系统通道直接输出，不允许第三方 App 截取原始音频流做音效处理或频谱分析。
为什么切到手机后台后，即使音乐还在播放，大曲库扫描也可能会暂停？ iOS 对后台进程的 CPU 与磁盘读写有严格的看门狗限制。如果后台边放歌边全速拉取几万首文件头和解压封面，系统会直接强杀进程导致音乐中断。因此切后台时 Primuse 会主动保存检查点（Checkpoint）并暂停重度扫描，切回前台立刻从断点接着扫。
为什么开了「与其他 App 同时播放」后，锁屏和耳机按键不能切歌？ 这是 iOS 音频会话的系统规则：开启混音模式（允许边玩游戏/看视频边听歌）后，系统不再把该 App 作为独占的「正在播放」控制对象。日常需要用锁屏、控制中心或耳机按键控制时，关闭「与其他 App 同时播放」即可恢复。
为什么「离线缓存音质」选了 AAC 转码，下载那一下还是消耗原文件流量？ 网盘（百度网盘、OneDrive 等）和 SMB/WebDAV 没有服务端转码能力，只能下发原文件，由手机芯片在本地转成 256k AAC 来节省 70% 以上的手机闪存空间。如果你用的是 Navidrome / Jellyfin / Emby 并想省移动流量，请在「播放设置 → 传输音质」中设置移动网络转码码率，由服务器转好再发给手机。