Overview
開始前
JiBA 是一個 macOS 圖形介面工具，用來直接在 Music.app 裡修復 Apple Music 中繼資料。根據你使用的模式和工具不同，它可能會更新歌曲標題、藝人、專輯、專輯藝人、部分排序欄位，以及用於恢復的回滾資訊。因為 JiBA 是直接寫入音樂資料庫的，所以修改結果可能透過 iCloud 音樂資料庫同步到你其他裝置上的 Apple Music。
幾個重要提醒
- 大規模全庫操作前，先讓 Music.app 的同步完成。
- 推薦的直接上手方式是保持預設 Auto Write 開啟，讓 JiBA 自動處理常規寫入。
- 只有在你想更保守、希望寫入前先看複核結果，或者這一批歌風險更高時，再關閉 Auto Write。
- 對特別大的資料庫，手動複核 / 手動寫入流程會更吃記憶體，甚至可能崩潰；預設自動寫入路徑沒有這個大庫問題。
- Refresh Music.app View、Web Player 相關工具等高級功能，可能會重啟 Music.app 或打開 Safari。
- 語言選擇列表中，各語言始終以該語言自己的名稱顯示，這是有意設計，不是遺漏。
快速上手
快速開始
如果你不想先通讀整份說明書，直接照下面這個順序用就可以。
推薦預設跑法
- 保持 Auto Write 開啟。這就是推薦的預設用法。
- 如果你要處理整個資料庫，就保持 All Library 開啟。
- 點擊 Run，讓 JiBA 自動寫入常規、低風險的匹配結果。
什麼時候切到手動複核
- 只有在你想更保守，或者想在寫入前先檢查一批風險更高的歌時，再關閉 Auto Write。
- 即使 Auto Write 開著，只要可疑分數太高，JiBA 仍可能把高風險項送進複核視窗。
- 對特別大的資料庫，手動複核 / 手動寫入流程會明顯更重，甚至可能崩潰；預設自動寫入路徑沒有這個大庫問題。
只修自己選的歌
- 先在 Music.app 裡選中你想修的歌曲。
- 回到 JiBA，把 All Library 關掉，這樣這次執行就只會針對目前 Music.app 選中上下文，不會掃全庫。
- 如果你想手動挑選結果，再把 Auto Write 關掉，執行後在複核視窗裡只套用你要的條目。
- 如果你接受直接寫回，就保持 Auto Write 開啟，直接對這批選中的歌執行。
Onboarding
首次啟動
如果 JiBA 在第一次執行時發現環境還沒準備好，就會彈出 setup sheet，也就是首啟引導。
模式選擇
Traditional
走本地匹配邏輯，不需要雲端啟用。適合第一次上手、先觀察結果是否符合預期的人。
Enhanced
走 JiBA 的雲端匹配路徑，覆蓋率和準確度更高，但需要透過捐贈流程啟用。在設定裡關閉 Enhanced Mode 時，Auto Write 也會一併關閉。
目標語言
選完模式後，JiBA 會讓你選擇要修復哪些目標語言。All Languages 會覆蓋下面個別的開關。
- Japanese (JP)：修復日語中繼資料。
- Sinitic Languages (Chinese)：開啟漢語族歌曲處理。
- Korean (KR)、Thai (TH)、English (US)、English (UK)、German (DE)、French (FR)、Spanish (ES)：允許對應目標地區參與匹配。
漢語族處理方式
如果你啟用了漢語族語言，JiBA 可能會再顯示一步用於選擇漢語族處理方式。這一步用來決定漢語族歌曲是保持區分，還是按你偏好的中文展示方式做歸一化。
Skip Setup
Skip Setup 會用相對安全的預設值跳過引導，後續你仍然可以在 Settings 裡慢慢調整。
Home
主視窗
主視窗是 JiBA 的核心操作介面。版面相對克制：頂部顯示狀態與進度，左側是執行控制，中間是快捷工具，右側是封面 / 目前播放。
| 區域 | 作用 |
|---|---|
| 頂部狀態區 | 顯示目前狀態、進度條、目前 / 總數、預計剩餘時間，以及 Help 按鈕。Help 會直接打開這份線上文件。 |
| Run | 依照目前 Settings 裡的預設配置啟動一次執行。 |
| Pause / Resume | 暫停或繼續目前執行，不會重新建立任務狀態。 |
| Stop | 請求安全停止目前執行。 |
| Trigger Regroup | 快速進入 Compilation regroup 修復流程，用來處理專輯在 Music.app 裡被拆開的情況。 |
| Metadata Repair | 快速跳到修復工具區，去掃描損壞中繼資料或打開修復複核視窗。 |
| Tips | 打開支持 / 捐贈流程。 |
| 封面面板 | 在 JiBA 工作時顯示相關封面與目前處理狀態。 |
幾個會影響執行方式的關鍵點
- 如果 Auto Write 關閉，JiBA 更像 dry run，會優先給你複核視窗，不直接寫入。
- 如果 Auto Write 開啟，JiBA 會自動寫入，但高風險項仍可能因為可疑分數過高而被攔進手動複核。
- 排程任務總是按「全庫 + 快取」來跑，是否自動寫入由另一個單獨開關決定。
Reference
設定詳解
Settings 是 JiBA 的主控制台。下面的分組順序和 GUI 裡實際看到的順序一致。
General 與 Operation Mode
| 選項 | 作用 |
|---|---|
| 首頁唱片樣式 | 在設定 → 一般中選擇 Neo，可依專輯封面自動配色；也可選擇原版黑膠。JiBA 1.5.1 需要 macOS 14 或更新版本。 |
| Language | 切換 JiBA 介面語言。語言列表裡每種語言保持以該語言自己的名稱顯示，這是產品特性。 |
| Show in Menu Bar | 決定 JiBA 是始終顯示在選單列、完全不顯示，還是僅在執行中顯示。 |
| Hide Dock icon | 讓 JiBA 以無 Dock 圖示的小工具方式執行。如果你隱藏了 Dock 圖示，建議保留選單列入口，方便重新打開。 |
| Enhanced Mode (Cloud API) | 切到雲端匹配路徑，取得更高覆蓋率與準確度。需要啟用。關閉時會順帶關閉 Auto Write。 |
Target Languages
| 選項 | 作用 |
|---|---|
| Target All Languages | 覆蓋下面各個個別語言開關，讓 JiBA 直接以「所有目標語言」模式執行。 |
| Japanese / Korean / Thai / English US / English UK / German / French / Spanish | 啟用對應目標地區作為中繼資料匹配來源。 |
| Sinitic Languages (Chinese) | 開啟漢語族歌曲處理。開啟後，JiBA 可能會顯示額外的漢語族處理方式選項。 |
| Sinitic Languages Handling | 決定漢語族歌曲最後如何被歸一化顯示。 |
| Language Detection | 選擇 Han-only 中繼資料的語言識別器，可選 Auto、Off、CLD3、fastlangid、langdetect。 |
| Allow Han-only metadata | 允許 JiBA 處理只有漢字、沒有假名的中繼資料。識別器不穩定時，可能增加日中誤判機率。 |
| Strict ID match | 讓匹配更保守，要求更強的 storefront 身份一致性。 |
| Force One Region For Entire Library | 跳過基於語言的區域判斷，強制整庫都只從一個地區拿中繼資料。只有當你明確想把整庫統一到同一地區時才建議開。 |
| Forced Region | 當強制地區模式開啟後，JiBA 實際固定使用的 storefront。 |
Schedule
| 選項 | 作用 |
|---|---|
| Auto run | 開啟或關閉排程任務。 |
| Start at login | 登入後自動啟動 JiBA。想讓排程任務長期穩定工作，通常都需要它。 |
| Mode | 在「固定間隔執行」與「固定時刻執行」之間切換。 |
| Interval | 在間隔模式下，依選定時間間隔重複執行。 |
| Repeat / Day / Time | 在固定時刻模式下，控制每天 / 每週、星期幾，以及具體執行時間。 |
| Time reference / Region / Reference time zone | 讓你按本地時間或指定時區時間來排程，並可先按洲 / 區域篩選時區。 |
| Next run | 預覽下一次執行時間。如果用了參照時區，還會一起顯示本地對應時間。 |
| Auto write for scheduled runs | 決定排程任務只是掃描 / 複核，還是排程任務也直接自動寫入。 |
Cache、預設執行、Performance、Updates、Advanced、Logging
| 選項 | 作用 |
|---|---|
| All Library | 以整個資料庫為目標，而不是只處理目前更窄的上下文。 |
| Auto Write | 允許 JiBA 自動寫入，而不是先進入偏複核導向的流程。 |
| Skip user-imported local tracks | 跳過你自己匯入的本地曲目，同時仍處理 iTunes 購買曲目與 Apple Music 入庫曲目。 |
| Scan for new tracks only | 只在全庫模式下有意義。開啟後盡量只處理新出現的曲目。 |
| Ignore Cache | 讓下一次執行忽略快取狀態。 |
| Clear Cache | 刪除 JiBA 的本機快取，等下次執行時重新建立。 |
| Auto threads / Threads | 要麼讓 JiBA 自動決定並行度，要麼手動指定執行緒數。 |
| Disable delay / Min / Max | 控制請求節奏。如果關閉 delay，JiBA 就不會插入這些等待。 |
| Prevent sleep while running tasks | 長任務執行期間阻止 Mac 進入睡眠。 |
| Check for updates automatically / Update channel / Check Now | 控制自動檢查更新、穩定版 / 測試版更新源，以及手動立即檢查。 |
| Reset to First Run Setup | 把 JiBA 恢復到首次啟動前的狀態，下次啟動時重新走引導。 |
| Show Advanced Options | 顯示或隱藏高級工具區。 |
| Deactivate Enhanced Mode | 清除目前這台 Mac 上的本機 Enhanced 啟用狀態。 |
| Ignore track number mismatch / Ignore disc number mismatch | 如果本地曲目的軌道號 / 碟號與 storefront 不一致，也允許匹配繼續。 |
| Repair: quarantine before write | 讓部分修復寫入先走隔離 / 保護式流程。 |
| Use v2 algorithm | 啟用更新的 signal-based 處理架構。 |
| Suspicious review threshold | 可疑分數達到這個閾值及以上時，即便是 Auto Write，也會先進手動複核。 |
| Deep historical scan | 讓 Damage Repair 掃描更久遠的 JiBA 歷史記錄，檢測範圍更廣，但速度更慢。 |
| Runtime dependencies: Check & Auto-install | 檢查目前執行依賴，並透過 JiBA 自帶的安裝流程自動補齊缺失項。 |
| Refresh Music.app View | 刷新或重啟 Music.app，並盡量恢復原來的播放上下文。 |
| Enable logging / Verbose / Open logs folder | 控制落盤日誌、額外詳細輸出，以及快速打開日誌目錄。 |
Repair
修復工具
Repair Tools 和 Advanced 區域裡放著 JiBA 最有威力的一批修復 / 恢復工具，建議按場景謹慎使用。
| 工具 | 作用 | 適用場景 |
|---|---|---|
| Nudge Grouping (Compilation) | 透過受控地切換 compilation 狀態，迫使 Music.app 重新整理被拆開的專輯。 | 當同一張專輯在 Music.app 裡被拆成多個塊時。先選中壞掉的專輯再執行。 |
| Scan Damaged Metadata | 掃描資料庫中的已知損壞模式、執行時問題痕跡，以及回滾快照線索。 | 當你懷疑舊版本 bug 或異常寫入導致 sort / album 等欄位損壞時。 |
| Review & Repair... | 打開 damage repair 複核視窗，處理掃描出來的候選項。 | 先掃描，再人工檢查後決定是否修復。 |
| Restore Original... | 讀取 JiBA 之前保存的回滾快照，把選中曲目恢復到記錄下來的原始中繼資料。 | 當你想撤銷 JiBA 之前的寫入結果時。 |
| Scan Dirty Tracks / Apply Repair | 找出同一專輯分組中的少數「髒軌」，並修復它們漂移的 album / album artist 資訊。 | 當一張專輯裡只有個別曲目的專輯資訊跑偏時。 |
| Refresh Music.app View | 刷新或重啟 Music.app，並盡力恢復原來的播放上下文。 | 當 Music.app 介面仍顯示舊中繼資料，或者視圖狀態明顯不對勁時。 |
| Repair Web Player Albums | 重寫影響 Web Player 的同步欄位，修復雲端曲目裡 sort album 與本地 album 不一致的問題。 | 當 Apple Music 網頁版出現空白專輯、undefined artist 之類現象時。 |
| Clean Web Player Orphan Albums | 打開 Safari，掃描 Web Player 專輯，並刪除符合嚴格「空殼條件」的孤兒專輯殼。 | 當 Web Player 雲端資料庫裡殘留空白殼專輯時。 |
Review
修復複核視窗
Damage Repair 的複核視窗，是 JiBA 裡資訊最密集、也是最關鍵的人工決策介面。
- Lookup region：指定修復查找時使用哪個 storefront。
- Filter：依執行時問題、找不到匹配、舊 damage 類型等篩選候選項。
- Lookup All：對目前可見候選一次性批量查找。
- Select Visible / Clear Visible：批量選擇或清空目前篩選結果。
- Apply Selected：把已選中的修復直接寫入。
- Ignore Next Time：告訴 JiBA 後續掃描裡先忽略這些結果。
- Restore Original：把選中曲目恢復到已保存的原始快照。
- Track-Level Only：當整專輯欄位寫入可能導致專輯被拆開時，只套用對單曲安全的欄位。
- Apply Anyway：跳過防拆專輯保護。只有你明確知道後果時才建議用。
狀態含義
Pending、Looking up metadata、Found、No change、Not found、Error 是每條候選最核心的狀態。可以據此判斷這首歌是否已經可以寫入、應該忽略，或者該換個 lookup region 再試。
Access
關於、幫助、選單列
JiBA 現在已經在多個位置都放了幫助入口，避免使用者找不到文件。
- 主視窗頂部：右上角的 Help 按鈕會打開線上文件。
- Settings 頂部：Help 按鈕也會打開同一份文件。
- About 視窗：Help 和更新、反饋、支持、群組入口並列放在一起。
- 無 Dock 圖示的選單列選單：也會包含 Help 項。
About 視窗另外還提供 Check for Updates、Feedback、Join Group、Tips、隱私政策以及專案網站入口。
Support
排錯
- 如果 JiBA 無法控制 Music.app，先確認 macOS 的 AppleEvents 權限是否允許。
- 如果跑完後 Music.app 還顯示舊介面或舊中繼資料，先試 Refresh Music.app View。
- 如果 JiBA 提示缺少 Python 依賴，先用 Runtime dependencies: Check & Auto-install，或者讓 JiBA 的自動安裝重試機制跑完。
- 如果你的資料庫裡混了很多不同地區版本，不要輕易打開 Force One Region For Entire Library。
- 如果你所在網絡環境本身就不穩定，尤其是限制較多的線路環境，API 失敗率會更高，建議網絡恢復後再重跑。