Skip to content

feat(apple-music-lyrics): add Apple Music desktop lyrics plugin - #533

Merged
ggbond268 merged 5 commits into
mactools-app:mainfrom
AndrewDi:apple-music-lyrics-plugin
Nov 18, 2026
Merged

ggbond268 merged 5 commits into
mactools-app:mainfrom
AndrewDi:apple-music-lyrics-plugin

Conversation

@AndrewDi

@AndrewDi AndrewDi commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

Summary

Add a new Plugins/AppleMusicLyrics/ plugin that shows frosted-glass desktop lyrics in the top-right corner while Apple Music plays. The plugin reads lyric documents already cached by Music.app locally, so it needs no Apple account, network request, or extra permission.

The floating window is a borderless NSPanel with an NSVisualEffectView (.hudWindow material) that stays on top without activating. Track and playback position are polled every 0.5 s from Music.app, and lyrics are matched by title, artist, album, and duration against the cached catalog responses.

Features

  • Configurable appearance: font size, background opacity, text opacity (independent), corner radius, text color, and next-line visibility.
  • Karaoke rendering: per-word sung/upcoming highlighting with a fallback whole-line gradient when per-word timings are absent. A 逐字渲染 / Karaoke rendering toggle lets users opt out; the description notes Apple Music's timing is approximate.
  • Draggable window: an opt-in drag toggle that persists the window position across launches.
  • Localization: 12 languages (zh-Hans, zh-Hant, en, ar, de, es, fr, ja, ko, pt, ru, tr).
  • Tests: 23 focused unit tests covering TTML parsing, cache lyric matching, karaoke rendering, text-color opacity scaling, and settings persistence/reset.

Documentation

  • docs/plugins/apple-music-lyrics.md: plugin guide with settings and manual verification steps.
  • README.md / README.zh-CN.md: feature paragraph in both languages.
  • changes/unreleased/apple-music-lyrics-plugin.md: changelog fragment.
  • docs/plugins/preferences-backup-inventory.md and site/src/generated/plugins.json: regenerated metadata.

Validation

  • ✅ make validate-changelog and make validate-localization pass.
  • ✅ 23 focused unit tests pass.
  • ✅ Adhoc-signed build succeeds; plugin dynamically loads in the host app.
  • ✅ Manual verification: window appears at top-right, karaoke sung/upcoming contrast is visible and can be toggled off, drag position persists across relaunch.

Notes

  • docs/plugins/catalog.json is intentionally left untouched (it is a signed release catalog regenerated by the release flow).

Add a new plugin that shows frosted-glass desktop lyrics in the
top-right corner while Apple Music plays. It reads lyrics already
cached by Music.app, so it needs no Apple account or network request.

Features:
- Configurable font size, background/text opacity, corner radius,
  text color, and next-line visibility
- Karaoke-style per-word highlighting with an opt-out toggle
- Draggable window position persisted across launches
- 12-language localization and focused unit tests

Includes a plugin guide, changelog fragment, README updates in both
languages, and regenerated plugin site data.
@ggbond2077

Copy link
Copy Markdown
Contributor

Thanks for adding desktop lyrics! I’d prioritize the first two fixes before merging.

  1. Keep MacTools responsive. The plugin waits for Music on the main thread every 0.5 seconds, so a slow reply can freeze the MacTools UI. Six polls while paused also triggered six host updates. Could you query Music asynchronously with a timeout, allow one request at a time, and notify the host only when the displayed state changes?
  2. Declare Automation access. Reading playback state sends Apple Events to Music, but the manifest and guide say no permission is needed. Please declare Automation access and update the guide. If access is denied, pause polling and point users to System Settings → Privacy & Security → Automation.
  3. Retry missing lyrics. If Music caches lyrics after the first lookup, they only appear after restarting the track. A few spaced retries while the same track is playing would let the lyrics appear as soon as a retry finds them.
  4. Keep the window closed after reset. Resetting while a lookup is running lets a late result reopen the window with the plugin disabled. Please reuse the disable cleanup and check that the plugin is still active and enabled before showing the result.
  5. Keep text opacity independent. With the background at 10% and text at 100%, the text also dims to 10%. Put the background and labels in sibling views so the background slider affects only the glass.
  6. Back up appearance preferences. The manifest declares no portable settings, so font size, colors, opacity, and karaoke preferences are lost on restore. Please include them in preference backups and keep screen coordinates and system permissions local to each Mac.

- Poll Music off the main thread with a 1.5s timeout and a single
  in-flight request, and notify the host only when displayed state
  changes, so a slow reply never freezes the UI.
- Declare Automation access in the manifest and pause polling with
  guidance when it is denied; re-enabling retries after the grant.
- Retry missing lyrics a few times while the same track plays so
  lyrics appear as soon as Music caches them.
- Cancel in-flight lookups and verify the plugin is still active
  before showing a result, keeping the window closed after a reset.
- Render the glass and the labels as siblings so background opacity
  no longer dims the text; text opacity stays independent.
- Back up appearance preferences while keeping activation, window
  position, and Automation permission local to each Mac.
- Add focused tests for polling, automation denial, backup round
  trip, and persistent-change signaling; update the guide, README,
  changelog, backup inventory, and regenerated site data.
@AndrewDi

Copy link
Copy Markdown
Contributor Author

Addressed all six review points:

  1. Responsive polling — Music is now polled on a cooperative worker with a 1.5 s timeout and a single in-flight request; the host is notified only when the displayed state actually changes.
  2. Automation access — the manifest declares the automation permission. On denial the plugin stops polling and the panel shows guidance to System Settings → Privacy & Security → Automation; re-enabling retries after the grant.
  3. Lyrics retry — missing lyrics are retried at 2/4/8 s while the same track is still playing, so lyrics appear as soon as Music writes them to the cache.
  4. Window closed after reset — reset reuses the disable cleanup (cancels in-flight lookups and clears state) and fetch/retry completion verifies the plugin is still active and enabled before showing a result.
  5. Text opacity independent — the glass and the labels are now sibling views, so backgroundOpacity dims only the glass and textOpacity stays independent.
  6. Preferences backup — appearance preferences (font, opacity, color, next-line, dragging, karaoke) transfer through Preferences Backup; activation, window position, and Automation permission stay local.

Verification: 28 focused unit tests pass (5 new), adhoc build succeeds, validate-changelog, validate-localization, validate-generated-plugin-data, and validate-backup-inventory pass. Manual check confirmed text stays fully opaque at 100% while the background is 10%, and karaoke sung/upcoming contrast is intact after the view restructure.

@ggbond268

Copy link
Copy Markdown
Collaborator

Thanks for the fixes! Polling now runs off the host's main thread and skips duplicate notifications. Automation access is declared, late lyrics appear without restarting the song, and the reset, text opacity, and appearance backup changes address the earlier feedback.

I reproduced two remaining cases with simulated Music responses:

  1. A slow request still blocks the next poll. With a three-second response, the 1.5-second deadline passed without reporting a timeout. The task group still waits for the synchronous AppleScript call to finish. Could you enforce the timeout on the Apple Event itself, or use an execution path that can stop the request at the deadline? Please keep the one-request limit.
  2. Permission denial leaves old lyrics on screen. When access was denied during playback, polling stopped but the last lyric stayed visible. Turning the feature off also left the old error in the panel. Please cancel pending lyric work, clear the track, and hide the window on denial. Clear the error when the feature is turned off or a later query succeeds, including when nothing is playing.

- Run the AppleScript round trip on a dedicated serial queue and report
  the 1.5s timeout at the deadline even though a synchronous AppleScript
  cannot be interrupted; the request slot stays occupied until the call
  actually returns, so at most one request is in flight.
- On an Automation denial, cancel pending lyric work, drop the track
  and lyrics, hide the window, and clear the error when the feature is
  turned off or playback stops or resumes.
- Invalidate in-flight requests on disable/reset so a late reply cannot
  reopen the window or apply stale state.
- Add tests for the timeout deadline, one-request limit, denial clearing
  the shown track, and error clearing on disable.
@AndrewDi

Copy link
Copy Markdown
Contributor Author

Addressed the two remaining cases:

  1. Slow request timeout — the AppleScript round trip now runs on a dedicated serial queue with a watchdog that reports the 1.5 s timeout at the deadline, even though a synchronous AppleScript call cannot be interrupted mid-flight. The request slot stays occupied until the call actually returns, so at most one request is in flight; late replies after a timeout are discarded (except an Automation denial, which is still honored).
  2. Stale state after denial — an Automation denial now cancels pending lyric work, drops the track and lyrics, hides the window, and clears the error when the feature is turned off or playback stops or resumes.

Verification: 31 focused unit tests pass (3 new), including a simulated 3 s Music reply that confirms the timeout is reported at the deadline and a second request is not started while the slot is occupied; and a denial-after-playback test that confirms the shown track is cleared. Adhoc build succeeds; manual playback confirms the window updates and the app stays responsive.

@ggbond268

Copy link
Copy Markdown
Collaborator

Thanks for the update! I confirmed that the timeout is now reported at the deadline, Automation denial clears the old lyrics and hides the window, and errors clear when the feature is turned off or a later query succeeds, including when nothing is playing.

One request-queue issue remains: disabling clears isFetchInFlight while the underlying Music query is still running, so re-enabling queues another query. With a simulated blocked response, three off/on cycles followed by disabling still caused three extra queries to run after the first was released.

Could you keep the request slot occupied until the underlying call finishes, separately from whether its result is still valid? Release the slot on completion even if the result is discarded, and cancel or skip invalidated queued queries before they execute. A focused check for disabling and re-enabling during a slow query would cover this case.

- Keep the request slot occupied until the underlying Music query actually
  finishes, decoupling it from whether the result is still wanted. Disabling
  or resetting no longer frees the slot, so re-enabling during a slow query
  cannot enqueue a second request behind the first.
- Release the slot unconditionally in the fetch completion, even when the
  result is discarded as invalidated.
- Skip an invalidated query at the head of the queue without running
  AppleScript, releasing the slot so polling resumes once re-enabled.
- Add a test that toggles the feature off and on during a slow query and
  asserts no extra requests are queued, then polling resumes after the slot
  frees.
@AndrewDi

Copy link
Copy Markdown
Contributor Author

Addressed the request-slot case:

The request slot is now decoupled from result validity. Disabling or resetting invalidates the in-flight/queued request (activeFetchRequestID) but no longer frees the slot (isFetchInFlight); the slot stays occupied until the underlying Music query actually finishes. The fetch completion releases the slot unconditionally, even when the result is discarded as invalidated. An invalidated query that is still queued is skipped at the head of the queue without running AppleScript, releasing the slot so polling resumes once re-enabled. This means toggling the feature off and on during a slow query cannot enqueue extra requests behind the first one.

Verification: 31 focused unit tests pass, including a new testDisableReenableDuringSlowQueryDoesNotQueueExtraQueries that simulates a 2 s Music reply, toggles the feature off and on three times while the request is blocked, and confirms no extra requests are queued and polling resumes after the slot frees. Adhoc build succeeds; manual playback confirms the lyrics window still appears and the app stays responsive.

@AndrewDi

Copy link
Copy Markdown
Contributor Author

@ggbond268 PTAL again

@ggbond268

Copy link
Copy Markdown
Collaborator

Thanks for the update! I reviewed 3e65f68. Invalidated queued queries are now skipped before calling Music, and the timeout reporting, Automation-denial cleanup, and preference-backup checks still pass.

One request-slot issue remains: while a Music query is blocked, toggle the feature off/on twice. The first disable clears the active request ID; the second sees no ID and clears isFetchInFlight, allowing another query to queue. When the original query finishes, it also clears the shared flag and cancels the newer query's timeout before checking its ID. A subsequent refresh can then replace that newer request and discard its valid result. I reproduced this with a fake Music service: a successful track reply left the displayed title empty.

Could you keep the actual request slot occupied independently of result validity, releasing it only when its own work finishes or is skipped? Repeated invalidation should only mark the result unwanted, and completion should cancel only that request's timeout. Please extend the test to check that a valid reply is applied after two off/on cycles and a refresh during the next query; counting started calls alone misses work waiting in the serial queue.

- Invalidate never frees the request slot: the slot is released only when
  the request's own work finishes or is skipped, so repeated disabling
  during a slow query cannot free the slot and let a re-enable queue a
  second request behind the first. A stale completion can no longer
  cancel a newer request's timeout or clobber its slot, so a later
  refresh's valid reply is applied instead of discarded.
- Make the polling interval settable so tests can disable the timer for
  deterministic timing of slow-query scenarios.
- Add a test that toggles the feature off and on twice during a slow
  query, refreshes during the next query, and asserts the valid reply is
  applied; it fails on the previous slot behavior.
@AndrewDi

Copy link
Copy Markdown
Contributor Author

Addressed the remaining request-slot case:

Invalidation no longer frees the request slot. The slot is released only when the request's own work finishes (the completion) or is skipped at the head of the queue, so repeated disabling during a slow query only marks the result unwanted and never frees the slot. Because the slot stays held, a stale completion can no longer cancel a newer request's timeout or clobber its slot, so a later refresh's valid reply is applied instead of being discarded.

Verification: 33 focused unit tests pass, including a new testValidReplyAppliedAfterTwoOffOnCyclesDuringSlowQuery that toggles the feature off and on twice during a 2 s simulated Music reply, refreshes during the next query, and asserts the refresh's valid reply is applied. I confirmed this test fails against the previous slot behavior and passes with the fix. Adhoc build succeeds; the app launches cleanly.

@ggbond268
ggbond268 merged commit 332a0f2 into mactools-app:main Nov 18, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants