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 | 选择汉字-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 失败率会更高，建议网络恢复后再重跑。