Primuse 全鏈路串聯指南與核心設計邏輯（為什麼這麼做）

功能說明

一、六個步驟把 Primuse 全套功能串起來用

1. 選對音樂源入口：按協定選，而不是只看裝置品牌

已有媒體伺服器（推薦，同步最快）：如果你已架設 Navidrome、Subsonic、Jellyfin、Emby、Plex、Audiobookshelf、Ting Reader、飛牛音樂或 Synology Audio Station，請直接新增對應的伺服器類型。伺服器已在背景建立索引，幾萬首歌只需幾十秒即可同步完目錄與播放清單。
NAS 共用資料夾與網盤：支援 Synology File Station、QNAP、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）並暫停重度掃描，切回前景立刻從斷點接著掃。

功能說明

一、六個步驟把 Primuse 全套功能串起來用

1. 選對音樂源入口：按協定選，而不是只看裝置品牌

已有媒體伺服器（推薦，同步最快）：如果你已架設 Navidrome、Subsonic、Jellyfin、Emby、Plex、Audiobookshelf、Ting Reader、飛牛音樂或 Synology Audio Station，請直接新增對應的伺服器類型。伺服器已在背景建立索引，幾萬首歌只需幾十秒即可同步完目錄與播放清單。
NAS 共用資料夾與網盤：支援 Synology File Station、QNAP、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）並暫停重度掃描，切回前景立刻從斷點接著掃。