Lyrics Fetcher

Getting started

Open Lyrics Fetcher and add music files or a folder you want to review. Test on **copied files** before using the app on an important library. Basic workflow: 1. Open Files… or Open Folder… 2. Scan to detect embedded lyrics 3. Fetch Lyrics (local folder → LRCLIB) or paste Manual lyrics 4. Enable metadata writing in Settings → Writing when you are ready to embed 5. Write Lyrics — confirm counts, then backup + embed + verify 6. Check Write status and View → Show Activity Log (⌘⇧L) Lyrics Fetcher embeds plain lyrics into **media files only** (MP3 USLT / M4A ©lyr). It never modifies Apple Music / Music.app database files on disk.

Supported providers

**Local folder provider** — When configured in Settings → Providers, the app can match `.txt` or `.lrc` files in a folder you choose. Local lookup does not use the network. **LRCLIB** — Optional HTTPS lookup to lrclib.net when Fetch Lyrics runs. LRCLIB is a community lyrics database; availability, accuracy, synchronization, and copyright status vary by track. The app does not scrape Google or arbitrary lyric websites. Provider order is local folder first, then LRCLIB when enabled.

Disabling LRCLIB and network access

To keep Fetch Lyrics offline, open Settings → Providers and **disable LRCLIB**. With LRCLIB disabled, the app should not send LRCLIB network requests during Fetch Lyrics. You can still scan files, use a local lyrics folder, paste Manual lyrics, and write when writing is enabled. macOS sandbox network.client remains for future provider work, but LRCLIB is the only outbound lyrics provider today.

Song matching and confidence

Each fetched result includes a **provider**, **match type**, and **confidence** (High, Medium, Low). Confidence reflects how closely the returned lyrics match your track metadata — not a guarantee that the lyrics are correct, complete, synchronized, or legally usable. Conservative write-readiness rules apply. Medium and risky matches may require manual approval or editing before writing. Settings → Writing can restrict writes to High-confidence matches only (default when writing is enabled). Versioned titles (demos, takes, remixes, live versions) may receive conservative caps when identity is ambiguous. When a match looks wrong, edit the lyrics, skip the write, or paste Manual lyrics instead.

Ambiguous results and manual review

Review the provider, confidence, match type, and lyric preview before any write. Use Manual lyrics or the edit flow to fix headers, section labels, or wrong verses. Export CSV, JSON, or TXT review reports when you want a record of the review session. App logs and Activity Log exports do not include full lyric bodies.

Plain versus synchronized lyrics

Lyrics Fetcher writes **plain** lyrics into MP3 (USLT) and M4A (©lyr) metadata. If a local `.lrc` file or LRCLIB response includes synchronized timestamps, the app may use that text as a source but the embedded tag written to your media file is plain lyrics, not a synchronized karaoke stream. Apple Music or device lyric displays may prefer catalog or synced sources when available.

Instrumental and not-found outcomes

Scan may classify a track as instrumental or with short/placeholder embedded lyrics. Fetch Lyrics may return **Not Found** when no acceptable candidate exists — that is expected for some tracks. Not Found does not mean the app failed; it means no provider returned a match that passed the app’s filters. Try a local lyrics file, Manual paste, or a different metadata spelling before writing.

Language and text encoding

Lyrics are handled as Unicode text. Tag reading and writing use TagLib and AVFoundation for supported MP3/M4A files. Unusual encodings or malformed tags may produce empty reads or write verification failures — keep backups and test on copies.

MP3 USLT and M4A lyrics embedding

Supported write formats: - **MP3** — ID3v2 unsynchronized lyrics frame (USLT) - **M4A** — QuickTime / Apple lyrics atom (©lyr) Other containers may be scanned for presence but are not writable by this app.

Backups and write verification

When writing is enabled, the app can create a sidecar backup (`*.lyricsfetcher.bak`) before modifying a file. Existing backup files are never overwritten and block new writes until you remove or rename them. After writing, the app re-reads the file to verify embedded lyrics length. Failed verification may restore from backup when available. Cancelled items are never reported as successful; files already written stay written. **Important:** test writes on copied files first. Keep backups enabled until you trust the workflow.

Batch scan, fetch, review, and write

Add many files via Open Folder… or repeated Open Files…. Scan processes the queue; Fetch Lyrics runs provider lookups for eligible rows; Write Lyrics operates on write-ready rows after confirmation. Use Cancel during long runs. Completed work remains; cancelled rows are not marked successful.

LRCLIB rate limits, timeouts, and temporary failures

LRCLIB may respond with rate limits (HTTP 429), timeouts, or temporary server errors. The app uses sequential requests with short delays between tracks and classifies failures in the Activity Log. Retry later when rate limited. Persistent Not Found for a track may require local lyrics or Manual entry — the service does not guarantee coverage for every song.

LRCLIB metadata and privacy

LRCLIB requests send **metadata only**: artist, title, album, and duration when available. **Audio files are never uploaded.** The app identifies itself with a User-Agent and Lrclib-Client header containing the app name, version, and https://h61apps.com/. LRCLIB responses are held in memory for the session and are not written to Activity Log bodies or URLs. See the shared [Privacy Policy](/privacy/) for site-wide practices. Support questions go to the [contact page](/contact/).

Apple Music and Music.app (optional)

After a verified file embed, Lyrics Fetcher can optionally update the matching **existing** Music.app library track’s `lyrics` property using Apple’s supported scripting interface. This is separate from file-write success. Matching uses file location and library metadata — the app does not edit Music library database package files on disk. **After writing:** confirm Write status is Written (and verification passed in the Activity Log). Import or locate the same file in Music.app, open Get Info (⌘I) → Lyrics, and expect Custom Lyrics for MP3/M4A embeds. **iCloud Music Library:** matched catalog tracks may ignore or override file-embedded Custom Lyrics after sync. If lyrics disappear, keep a local copy, re-import without matching, or re-check Get Info on the Mac that performed the write. **Devices:** downloaded tracks may still show Apple’s lyric source when available. Synced/karaoke lyrics are not written by this app.

Automation and music-library permissions

Optional Music library updates require Automation permission for Music.app the first time the feature runs with the setting enabled. Media Library access may be requested for library matching via system APIs. You can disable Music library updates in Settings → Writing. Denying Automation leaves file writes intact but Music Library status may show permission denied.

Sandbox, NAS, and folder bookmarks

The app runs in the macOS sandbox. Open Files…, Open Folder…, and drag-and-drop grant access to user-selected paths. App-scoped bookmarks remember folder access across launches. Network-attached storage (NAS) paths may require Conservative Network Scanning and folder re-authorization if macOS revokes access. If scan or write fails with a permission error, re-open the folder and retry.

Activity Log and export

View → **Show Activity Log** (⌘⇧L) opens a separate diagnostic window. **Export Activity Log…** saves a text file through the standard save panel. The log records workflow events and errors. It does not include full lyric text, LRCLIB request URLs, API secrets, or tokens.

Shortcuts

⌘O Open Files… ⌘⇧O Open Folder… ⌘R Scan ⌘F Fetch Lyrics ⌘⇧W Write Lyrics (when writing enabled) ⌘. Cancel ⌘⇧L Show Activity Log ⌘? Lyrics Fetcher Help (this page)

Copyright, provider limitations, and your responsibility

Lyrics may be protected by copyright. LRCLIB and local files provide text for your review; **you are responsible** for deciding whether storing or embedding retrieved lyrics in your files complies with applicable law and the terms of any service or content provider. Lyrics Fetcher does not claim that lyrics are always available, accurate, synchronized, or legally redistributable. When in doubt, use lyrics you own or are licensed to embed.

Troubleshooting

• If a match looks wrong, edit it, skip the write, or use Manual lyrics. Conservative readiness rules are intentional.
• If Fetch Lyrics fails for every track, confirm LRCLIB is enabled and network access is available, or disable LRCLIB and use local/Manual lyrics.
• If a write fails, confirm the file is MP3 or M4A and that the app has write access to the folder (re-authorize NAS folders if needed).
• If verification fails, inspect the file and any `.lyricsfetcher.bak` backup before re-importing into Music.app.
• For product questions or bugs, use the H61 contact page and include app version, macOS version, and an Activity Log export when helpful.