Repository navigation
feat(apple-music-lyrics): add Apple Music desktop lyrics plugin - #533
Conversation
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.
|
Thanks for adding desktop lyrics! I’d prioritize the first two fixes before merging.
|
- 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.
|
Addressed all six review points:
Verification: 28 focused unit tests pass (5 new), adhoc build succeeds, |
|
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:
|
- 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.
|
Addressed the two remaining cases:
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. |
|
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 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.
|
Addressed the request-slot case: The request slot is now decoupled from result validity. Disabling or resetting invalidates the in-flight/queued request ( Verification: 31 focused unit tests pass, including a new |
|
@ggbond268 PTAL again |
|
Thanks for the update! I reviewed 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 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.
|
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 |
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
NSPanelwith anNSVisualEffectView(.hudWindowmaterial) 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
逐字渲染 / Karaoke renderingtoggle lets users opt out; the description notes Apple Music's timing is approximate.zh-Hans,zh-Hant,en,ar,de,es,fr,ja,ko,pt,ru,tr).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.mdandsite/src/generated/plugins.json: regenerated metadata.Validation
make validate-changelogandmake validate-localizationpass.Notes
docs/plugins/catalog.jsonis intentionally left untouched (it is a signed release catalog regenerated by the release flow).