Overview
Before You Start
JiBA is a macOS GUI for repairing Apple Music metadata directly inside Music.app. Depending on the tool or mode you use, it can update track title, artist, album, album artist, some sort fields, and related recovery metadata. Because JiBA writes into your Music library, changes can sync to your other Apple Music devices through iCloud Music Library.
Important safety notes
- Let Music.app finish syncing before large library-wide runs.
- The recommended quick-start path is to leave Auto Write on and let JiBA handle straightforward writes automatically.
- Turn Auto Write off only if you want a more conservative review-first pass or need to inspect riskier batches before anything is written.
- On very large libraries, the manual review / manual write flow can use much more memory and may crash. The default automatic write path does not have that large-library review bottleneck.
- Advanced tools such as Refresh Music.app View and Web Player repair actions may relaunch Music.app or open Safari.
- The language picker intentionally keeps language names written in their own native language. That behavior is intentional.
Start Here
Quick Start
If you want the recommended way to start using JiBA without reading the full reference first, use this order.
Recommended default run
- Leave Auto Write on. That is the recommended default path.
- Leave All Library on if you want JiBA to work across the full library.
- Press Run and let JiBA write ordinary matches automatically.
When to switch to manual review
- Turn Auto Write off only if you want a safer review-first pass or need to inspect a riskier batch before writing.
- Even with Auto Write on, JiBA can still divert higher-risk items into review if they cross the suspicious review threshold.
- On very large libraries, the manual review / manual write flow can be much heavier and may crash. The default automatic write path does not have that large-library issue.
Repair only specific songs
- In Music.app, select the songs you want to repair first.
- In JiBA, turn All Library off so the run stays on the current Music.app context instead of the whole library.
- If you want to hand-check every change, turn Auto Write off, run JiBA, then apply only the rows you want from the review sheet.
- If you are comfortable with direct write-back, keep Auto Write on and run JiBA against that smaller selected context.
Onboarding
First Launch
If JiBA does not detect a ready environment on first launch, it opens the setup sheet. That sheet is the guided onboarding flow.
Mode selection
Traditional
Uses local matching logic. It is the simplest entry point, does not require cloud activation, and is the safest place to start if you want to verify behavior first.
Enhanced
Uses JiBA’s cloud-backed matching path for higher coverage and accuracy. It requires activation through the donation flow. In Settings, turning Enhanced Mode off also turns Auto Write off.
Target languages
After mode selection, JiBA asks which target languages you want it to fix. All Languages overrides the individual switches below it.
- Japanese (JP): restore Japanese metadata.
- Sinitic Languages (Chinese): enable Han-family song handling.
- Korean (KR), Thai (TH), English (US), English (UK), German (DE), French (FR), Spanish (ES): enable those storefront targets.
Sinitic handling
If Sinitic Languages are enabled, JiBA may show a second step for Han-family handling. That decides whether Han-family songs stay differentiated or are normalized into a preferred Chinese presentation mode.
Skip Setup
Skip Setup exits onboarding with safe defaults and lets you configure everything later in Settings.
Home
Main Window
The main window is the operational home for JiBA. It is deliberately compact: status and progress at the top, run controls on the left, quick tools in the middle, and artwork / now playing on the right.
| Area | What It Does |
|---|---|
| Status header | Shows current state, progress bar, current/total count, estimated remaining time, and a Help button that opens the online documentation. |
| Run | Starts a run using the current defaults and selections already stored in Settings. |
| Pause / Resume | Temporarily suspends the active run and resumes it without rebuilding state. |
| Stop | Requests a clean stop for the active run. |
| Trigger Regroup | Shortcut into the compilation regroup workaround for albums that split incorrectly. |
| Metadata Repair | Shortcut into the repair tool area so you can scan damaged metadata or open repair review quickly. |
| Tips | Opens the support / donation flow. |
| Artwork panel | Shows the active artwork / now playing state while JiBA is working. |
Run behavior that matters
- If Auto Write is off, JiBA behaves like a dry run and can open review sheets before anything is written.
- If Auto Write is on, JiBA writes automatically, but high-risk items can still be diverted into manual review if they cross the suspicious review threshold.
- Scheduled runs always use the full library and cache. A separate toggle decides whether scheduled runs also auto write.
Reference
Settings Reference
Settings is where almost all JiBA behavior is controlled. The sections below follow the same group order as the GUI.
General and Operation Mode
| Option | What It Does |
|---|---|
| Homepage Record Style | Choose Neo for colored vinyl based on the album artwork, or Original Vinyl for the classic look. Find this option in Settings → General. JiBA 2.0.0 requires macOS 14 or later. |
| Language | Changes the JiBA interface language. The list intentionally keeps each language name written in its own native form. |
| Show in Menu Bar | Controls whether JiBA is always shown in the menu bar, never shown there, or only shown while running. |
| Hide Dock icon | Runs JiBA as a dockless utility. If you hide the Dock icon, keep a menu bar entry available so you can reopen the app easily. |
| Enhanced Mode (Cloud API) | Switches JiBA to cloud-backed matching for better results. Requires activation. Turning it off also turns Auto Write off. |
Target Languages
| Option | What It Does |
|---|---|
| Target All Languages | Overrides the individual language switches and lets JiBA target every enabled storefront family. |
| Japanese / Korean / Thai / English US / English UK / German / French / Spanish | Enables that target region family for metadata resolution. |
| Sinitic Languages (Chinese) | Enables Han-family matching. When this is on, JiBA can show an additional handling mode picker. |
| Sinitic Languages Handling | Changes how Han-family songs are normalized once Chinese-family matching is enabled. |
| Language Detection | Selects which detector JiBA should use for ambiguous Han-only metadata. Options include Auto, Off, CLD3, fastlangid, and langdetect. |
| Allow Han-only metadata | Lets JiBA operate on Han-only metadata even though that can blur Japanese vs Chinese distinction when detection is weak. |
| Strict ID match | Keeps matching more conservative by requiring stronger storefront identity agreement. |
| Force One Region For Entire Library | Bypasses language-based region judgment and always resolves from one selected region. Use only if you intentionally want one storefront applied across your entire library. |
| Forced Region | The exact storefront JiBA uses once forced-region mode is enabled. |
Schedule
| Option | What It Does |
|---|---|
| Auto run | Turns scheduled execution on or off. |
| Start at login | Lets JiBA launch automatically when you sign in, which is usually needed for schedules to work reliably. |
| Mode | Choose between interval-based scheduling and a custom clock time. |
| Interval | When interval mode is selected, runs JiBA every chosen amount of time. |
| Repeat / Day / Time | When custom time is selected, controls daily vs weekly recurrence, weekday selection, and exact run time. |
| Time reference / Region / Reference time zone | Lets you schedule using local time or a fixed reference time zone, including a region filter to find time zones more quickly. |
| Next run | Preview showing the calculated next execution time in reference time and, when relevant, local time. |
| Auto write for scheduled runs | Determines whether scheduled runs only scan / review or actually write automatically. |
Cache, Run Defaults, Performance, Updates, Advanced, Logging
| Option | What It Does |
|---|---|
| All Library | Targets the full library instead of a narrower current context. |
| Auto Write | Writes automatically instead of waiting for a review-oriented flow. |
| Skip user-imported local tracks | Skips tracks you imported manually while still allowing iTunes purchases and Apple Music library tracks to be processed. |
| Scan for new tracks only | Only relevant in full-library mode. Limits the run to newly discovered material. |
| Ignore Cache | Forces JiBA to disregard cached state for the next run. |
| Clear Cache | Deletes JiBA’s local cache before the next run. |
| Auto threads / Threads | Either let JiBA choose concurrency automatically or set a manual thread count. |
| Disable delay / Min / Max | Controls request pacing. If delay is disabled, JiBA does not insert those waits. |
| Prevent sleep while running tasks | Keeps the Mac awake during long operations. |
| Check for updates automatically / Update channel / Check Now | Controls automatic update checks, stable vs beta feed, and manual update checks. |
| Reset to First Run Setup | Resets JiBA to onboarding state and requires setup again on next launch. |
| Show Advanced Options | Reveals the advanced tool section inside Settings. |
| Deactivate Enhanced Mode | Clears the local Enhanced activation state on this Mac. |
| Ignore track number mismatch / Ignore disc number mismatch | Relaxes metadata matching if local numbering differs from storefront numbering. |
| Repair: quarantine before write | Places tracks into a quarantine-style workflow before certain repair writes. |
| Use v2 algorithm | Enables the newer signal-based architecture. |
| Suspicious review threshold | Issues at or above this score are diverted into manual review before auto-write runs commit them. |
| Deep historical scan | Expands damage detection by scanning deeper JiBA history. It is slower. |
| Runtime dependencies: Check & Auto-install | Checks current runtime dependencies and auto-installs missing ones through JiBA’s install pipeline. |
| Refresh Music.app View | Refreshes Music.app and attempts to restore the current playback context afterward. |
| Enable logging / Verbose / Open logs folder | Controls disk logging, extra output detail, and direct access to JiBA’s log directory. |
Repair
Repair Tools
The Repair Tools and Advanced sections hold the highest-impact recovery utilities in JiBA. Use them deliberately.
| Tool | What It Does | When To Use It |
|---|---|---|
| Nudge Grouping (Compilation) | Toggles compilation state in a controlled way to force Music.app to regroup a broken album. | When one album is visually split in Music.app. Select the broken album first. |
| Scan Damaged Metadata | Scans the library for known JiBA damage patterns, runtime issue traces, and rollback evidence. | When you suspect earlier bugs or partial writes damaged album / sort metadata. |
| Review & Repair... | Opens the damage repair review sheet for candidates found by the scan. | After a damage scan, when you want to inspect and selectively repair findings. |
| Restore Original... | Loads stored rollback snapshots and restores the original metadata JiBA saved before writing. | When you want to undo previous JiBA writes and revert tracks back to their recorded original state. |
| Scan Dirty Tracks / Apply Repair | Looks for minority tracks inside the same album grouping and repairs album metadata drift. | When one or two tracks inside an album have wrong album or album artist values. |
| Refresh Music.app View | Relaunches or refreshes Music.app and tries to restore the previous track context. | When Music.app UI looks stale or still shows older metadata after a run. |
| Repair Web Player Albums | Rewrites Web Player-facing sync fields for cloud-backed tracks whose sort album no longer matches the current local album. | When Apple Music Web Player shows blank albums or undefined artists. |
| Clean Web Player Orphan Albums | Opens Safari, scans Web Player albums, and removes empty orphan album shells that match strict blank-shell criteria. | After Web Player corruption leaves blank shells in your cloud library. |
Review
Repair Review Sheet
The damage repair review sheet is the most detailed decision surface in JiBA. It is where you inspect candidates before applying or restoring metadata.
- Lookup region: choose which storefront to query for repair lookup.
- Filter: limit the sheet to runtime issues, not-found cases, legacy damage, and other categories.
- Lookup All: resolve metadata for all visible candidates in one pass.
- Select Visible / Clear Visible: bulk-select or clear the current filtered set.
- Apply Selected: writes the selected fixes.
- Ignore Next Time: suppresses selected results from future scans.
- Restore Original: restores the saved original metadata snapshot for the selected tracks.
- Track-Level Only: appears when album-level writes would split an album; it applies only track-safe fields.
- Apply Anyway: bypasses the album-splitting safeguard. Use only if you fully understand the consequence.
Status meanings
Pending, Looking up metadata, Found, No change, Not found, and Error are the key per-candidate states. Use them to decide whether a track is ready to write, should be ignored, or needs a different lookup region.
Access
About, Help, Menu Bar
JiBA now exposes documentation from multiple places so users do not need to hunt for it.
- Main window header: the Help button in the upper-right opens the online guide.
- Settings header: the Help button opens the same guide.
- About window: includes Help alongside update, feedback, support, and group actions.
- Dockless menu bar menu: includes Help when JiBA is running without a Dock icon.
The About window also includes Check for Updates, Feedback, Join Group, Tips, the privacy policy, and the project site.
Support
Troubleshooting
- If JiBA cannot control Music.app, make sure macOS AppleEvents permissions were granted.
- If Music.app still shows stale UI after a run, use Refresh Music.app View.
- If JiBA reports missing Python dependencies, use Runtime dependencies: Check & Auto-install or allow JiBA’s automatic install retry to complete.
- If your library mixes storefronts heavily, do not enable Force One Region For Entire Library unless that is exactly what you want.
- If you are on unstable network routes, especially in restricted environments, expect more API failures and consider rerunning after connectivity stabilizes.