Add taskbar-fluent-media-player-lx mod (LX Music lyrics + Chinese localization)

[zq20180515]

Summary

This PR adds a new mod: taskbar-fluent-media-player-lx, a fork of Taskbar Fluent Media Player that adds real-time LX Music lyrics display in the Windows 11 taskbar media player, plus full Chinese localization of all settings and visualizer overlay improvements.

Features

LX Music Lyrics

• Displays the current lyric line at the bottom of the taskbar media player, extending beneath the playback controls
• Dual-line lyrics: current line (large) + next line (small, semi-transparent), parsed from full LRC lyrics via LX Music Open API
• Customizable lyric font size, font family, color (supports #RRGGBB and R G B), and optional text shadow
• Configurable spacing between song title and lyrics (supports negative values for overlap)
• No-lyric fallback: automatically show artist name or collapse the lyric row
• Pure music lyric auto-detection (e.g. "纯音乐，请欣赏" is treated as no lyric)

Chinese Localization

• All mod settings (player, appearance, behavior, animation, visualizer, debug, etc.) have been fully translated to Simplified Chinese ($name:zh-CN / $description:zh-CN)
• Mod name and description localized in both Chinese and English

Visualizer Overlay Improvements

• New overlay mode for the audio visualizer: overlaps the visualizer beneath the song title and lyrics (but not the album art), instead of only left/right placement
• Visualizer color in overlay mode defaults to light gray semi-transparent for readability
• Adjustable overlay opacity setting (0-100)

Preserved

• All original mod features intact (album art, media controls, playback sessions, mini player, etc.)

Requirements

• LX Music Desktop v2.7.0+ with "Open API service" enabled (default port: 23330)
• The mod fetches lyrics via http://127.0.0.1:port/status

Screenshots

Mod authorship

• [✅] The submitter, with AI assistance
• [✅] Another AI (please specify): Doubao

[windhawk-reviewer]

Thanks for the pull request! This repository uses a two-stage review: an AI review that you run yourself, followed by a human review.

To get started, comment /ai-review. Once you're happy with the result, comment /ready-for-reviewer to hand it over to a human reviewer.

See the pull request review process for the full details.

[zq20180515]

/ai-review

[windhawk-reviewer]

Submission review

Note: This review was done by Claude. Due to the amount of submissions, doing a fully manual review for each pull request is no longer feasible. Thank you for understanding.

Remember: The AI reviewer can be wrong - it may misread code, flag correct code as broken, or suggest changes that make things worse. Treat its findings as suggestions to verify, not instructions to follow blindly. You're responsible for the code you submit, so if a finding doesn't hold up, say so instead of changing working code to satisfy it.

Please address the following issues. The items in the collapsed sections are optional, so it's your call whether to address them.

---

The lyric feature itself is put together carefully (LRC parsing, dual-line rendering, scroll reuse), but the submission has a catalog-level problem and a few defects that will bite users.

1. This is a near-complete copy of an existing catalog mod. taskbar-fluent-media-player is already in the repo; diffing the two files (after normalizing line endings — the submission converted the whole file from CRLF to LF, which is why the PR diff shows 11k lines) gives 949 added and 208 removed lines against 10,280 — i.e. ~91% of the submission is Salyts' code verbatim.

Windhawk's strong preference is to extend an existing mod rather than merge a fork of it: two nearly identical entries fragment the catalog, confuse users choosing between them, and every upstream fix has to be hand-ported forever. All three of your additions are natural upstream features:

• LX Music lyrics → a new optional settings group, off by default
• zh-CN localization → $name:zh-CN / $description:zh-CN next to the existing ru-RU strings
• visualizer overlay mode → a new "overlay" value for the existing vizPosition option

Please take these to the original project as a PR / feature request: https://github.com/Salyts/Taskbar-Fluent-Media-Player. If the author declines, say so here and we can discuss, but a standalone fork should be the last resort.

2. The English user-facing strings were deleted and replaced with Chinese. Mod name, @description, and ~150 setting $names are now Chinese-only (the $name:ru-RU translations were kept, but the English originals — $name: Media player position, $name: Monitor, $name: Album Art, … — were overwritten). English is the default language for Windhawk mods; other languages go in the localization suffixes. Restore every English $name/$description/@name/@description and add $name:zh-CN alongside. Note this is already inconsistent inside your own new settings, where most entries have an English $description but a Chinese $name.

3. static std::thread g_lxThread; (line 4714) crashes Explorer on every shutdown. Wh_ModUninit is only called on a controlled unload (disable/reload). When the host process terminates — Explorer restart, sign-out, reboot — it is not called, so the global is still joinable() when the CRT runs its destructor, and ~std::thread() calls std::terminate(), aborting explorer.exe. The same file already has the correct pattern 150 lines below, for the visualizer capture thread:

[[clang::no_destroy]] static std::optional<std::thread> g_CaptureThread;   // line 4871

Mirror it: [[clang::no_destroy]] static std::optional<std::thread> g_lxThread;, g_lxThread.emplace(LxPollThreadProc) in StartLxThread, and join() + reset() in StopLxThread — exactly like StopCaptureThread. Background: https://github.com/ramensoftware/windhawk/wiki/Global-objects-and-process-shutdown (see #1 Worker thread (std::thread)).

4. LxFetchStatus sets no WinHTTP timeouts, so unloading the mod can hang Explorer. WinHttpOpen at line 4674 uses the defaults: resolve = infinite, connect = 60 s, send/receive = 30 s. StopLxThread() joins the poll thread, and it is called from Wh_ModUninit and Wh_ModSettingsChanged, so an in-flight request blocks the unload for however long WinHTTP takes. With the default 127.0.0.1 a refused connection returns fast, but lxHost is a free-text setting — a hostname whose DNS black-holes makes Wh_ModUninit never return, hanging the mod update/disable. Add right after WinHttpOpen:

WinHttpSetTimeouts(hSession, 2000, 2000, 2000, 2000);

5. lxHost allows pointing the mod at an arbitrary remote server. Windhawk mods must be self-contained and must not contact external servers. Please drop the host setting and hardcode 127.0.0.1 (keeping the port configurable), or at minimum reject anything that isn't a loopback address.

6. The "controls up offset" silently stops working after any settings change. g_lyricsCtrlShift (line 3138) caches the last applied shift, but it is never reset when the player is rebuilt. Wh_ModSettingsChanged calls RemovePlayerGrid() + InjectPlayerGrid() (line 10999), producing a fresh ctrlPanel/textStack with no RenderTransform — yet g_lyricsCtrlShift still holds the old value (e.g. 6.0), so std::abs(shift - g_lyricsCtrlShift) > 0.1 is false and the transform is never re-applied. The lyric row then overlaps the buttons until the user toggles playback state enough to change shift. Reset g_lyricsCtrlShift = -1.0 wherever the grid is (re)built (InjectPlayerGrid / RemovePlayerGrid).

7. Enabling lyrics silently overrides the user's "Media player height (min max)" setting. Line 8033:

if (g_settings.lxEnabled) {
    if (phMin < 56.0) phMin = 56.0;
    if (phMax > 0.0 && phMax < 56.0) phMax = 56.0;
}

lxEnabled defaults to true, so the documented playerHeight default of "40 40" has no effect out of the box, and 56 px is taller than a default Windows 11 taskbar (~48 px). Either compute the extra room from the actual lyricFontSize / lyricSecondLineSize / lyricTopSpacing values and add it to the user's setting, or leave the setting authoritative and document the height requirement in the README.

8. Attribution, license and README. The README keeps Salyts' full feature list but deletes the upstream Credits section (Salyts as author, GR0UD for the visualizer engine), the issue-report link, and all screenshots. Please restore the credits, and add an @license compatible with the upstream project's license — this mod is ~91% someone else's code. Two more:

• The README has no image at all now. This mod has a very visible effect, so please include at least one screenshot/GIF of the lyric row (allowed hosts: i.imgur.com and raw.githubusercontent.com).
• @github is https://github.com/zq20180515/windhawk-mods/new/main/mods — that's GitHub's "create a new file" editor URL. It should be your profile or the mod's repository.

Optional improvements

Minor polish — none of this affects users much, so it's your call.

• LyricColor() line 2831: after trimming, s.front() is called without checking that s is still non-empty. A lyricColor of " " passes the !empty() guard, trims to "", and front() on an empty string is undefined behavior. Add if (s.empty()) return ArtistColor(); after the trim.
• Same function: the hex branch triggers on any 6-character value, so a space-separated "12 3 4" is parsed as hex 0x12 0x03 0x04 instead of 12 3 4. Take the hex path only when the value started with # or contains no spaces.
• LxFetchStatus builds and tears down a WinHTTP session + connection on every poll (once per second, forever). Create them once for the thread's lifetime and only open the request per poll.
• For a loopback request, prefer WINHTTP_ACCESS_TYPE_NO_PROXY over WINHTTP_ACCESS_TYPE_DEFAULT_PROXY, so a machine-wide WinHTTP proxy config can't intercept it.
• TextBlock lyricShadowBlock; and TextBlock lyricSecondBlock; are constructed unconditionally and discarded when lyricShadow / lyricDualLine are off. Construct them inside the corresponding if.
• enableMiniPlayerPopup overlaps with what's already there: the mini player only opens when the user binds the open_mini_player click action, so the new switch is a second way to disable the same thing. Consider dropping it.

Functionality notes

Non-critical observations and ideas about the feature behavior itself.

• Lyric timing. Polling /status once per second means the displayed line can lag the music by up to a second, which is noticeable for fast lyrics. Since you already fetch progress and parse the full LRC, you could advance the current/next line locally from a monotonic clock between polls and only resync on each poll — accurate timing without increasing the poll rate.
• Redundant work per poll. Every poll requests the full lyric (whole LRC) and re-runs ParseLrcLines + std::sort over it. Cache the parsed std::vector<LrcLine> and only re-fetch/re-parse when the track changes.
• Fixed poll rate. The thread polls every second regardless of whether LX Music is running, whether there's a media session, or whether the player is hidden. Backing off (e.g. to 5–10 s) after consecutive connection failures, and skipping polls while the player is hidden, would cut the constant TCP-connect churn inside explorer.exe.
• IsPureMusicLyric hardcodes 纯音乐. Users running LX Music with a non-Chinese UI will see the placeholder line rendered as a lyric. Matching whatever marker LX Music emits per language, or exposing the string as a setting, would generalize it.
• JSON parsing is substring-based. LxFindJsonString/LxFindJsonNumber search for "key" anywhere in the payload, so a key name occurring inside another string value would produce a wrong match. It's fine for this fixed endpoint, but it's a latent fragility if LX Music's response shape changes.
• Single-player coupling. The lyric row only ever works with LX Music, while the rest of the mod is player-agnostic via GlobalSystemMediaTransportControlsSession. A thin provider abstraction (LX Music today, others later) would make the feature much easier to justify upstream.

---

Next steps:

• /ai-review - after pushing fixes, to get a review of the updated code. You can repeat this as many times as you need, but each review is thorough and usually there's no need for more than 2-3 iterations.
• /ready-for-reviewer - once you're satisfied with the state of the pull request, to hand it over to a human reviewer. If some findings above are left unaddressed, add a short note explaining why.

See the review process for details.

[zq20180515]

/ai-review

[windhawk-reviewer]

Submission review

Note: This review was done by Claude. Due to the amount of submissions, doing a fully manual review for each pull request is no longer feasible. Thank you for understanding.

Remember: The AI reviewer can be wrong - it may misread code, flag correct code as broken, or suggest changes that make things worse. Treat its findings as suggestions to verify, not instructions to follow blindly. You're responsible for the code you submit, so if a finding doesn't hold up, say so instead of changing working code to satisfy it.

Please address the following issues. The items in the collapsed sections are optional, so it's your call whether to address them.

---

The lyrics feature itself is a nice idea and the LX API integration is mostly sound, but the submission is structured as a full fork of an existing catalog mod, and the localization pass damaged the English settings UI. Those two need resolving before anything else.

1. This is a near-duplicate of an existing mod in the catalog. mods/taskbar-fluent-media-player.wh.cpp by Salyts is already merged, and this submission is that mod's 1.6.0 source with roughly 1,000 of its 11,269 lines changed — the other ~10,200 are byte-identical. Windhawk's strong preference is to extend an existing mod rather than merge a fork: two mods with the same 200-setting UI, the same bugs and diverging fixes fragment the catalog and confuse users, and only one of them will receive upstream fixes.

The three additions here are all self-contained and none of them require forking:

• LX Music lyrics — this is orthogonal to the media player. It could be a small standalone mod that only draws a lyric line, or an option contributed to the upstream mod.
• Visualizer overlay mode and enableMiniPlayerPopup — these are plain feature additions to the original mod, ~60 lines total.
• Chinese localization — pure metadata; upstream already carries ru-RU strings, so a zh-CN pass is exactly the kind of contribution the original repo would take.

Please open a PR against Salyts/Taskbar-Fluent-Media-Player for the localization, the overlay mode and the popup toggle, and if the lyrics feature isn't wanted upstream, submit it here as its own small mod instead of a fork of the whole player.

2. README images are on a disallowed host. Only i.imgur.com and raw.githubusercontent.com are allowed. Both screenshots (lines 66/68 and 116/118) use https://github.com/user-attachments/assets/..., which will not work — re-upload them to Imgur or to a repo of yours and link via raw.githubusercontent.com.

3. The Chinese localization pass overwrote ~20 English setting names with their parent group's name. In each settings group the last child's English $name was replaced by the group heading, while the zh-CN/ru-RU names stayed correct. So the English (default) settings UI now shows wrong labels. Example at line 299:

    - fullHeightHitArea: true
      $name: Media player                      # should be "Full-height invisible hit area"
      $name:zh-CN: 全高不可见点击区域           # correct
      $name:ru-RU: Невидимая область клика на всю высоту

The affected settings, with the correct upstream text:

Setting	Current English $name	Should be
fullHeightHitArea	Media player	Full-height invisible hit area
albumArtMargin	Album Art	Album art margin (left right)
noMediaArtistText	Text area	Artist text when nothing is playing
hideUnsupportedButtons	Media Buttons	Hide unsupported buttons
vizSensitivity	Main Settings	Sensitivity (0-300)
enableHoverAnimation	Background Style	Smooth hover animation
buttonColorOpacity	Media Buttons Style	Media buttons icons opacity (0-100)
titleCharacterSpacing	Title Text Style	Title character spacing
artistCharacterSpacing	Artist Text Style	Artist character spacing
appIconSize	Album Art Display	App icon size
vizColor2	Appearance Settings	Gradient color 2 (RGB)
hideMediaSessionsList	Player Menu Settings	Hide media sessions list
ClickActionSettings.action	Click Actions	Action
MouseWheelActionSettings.action	Mouse wheel Actions	Action
showFullTitleOnHover	Behavior Settings	Show full track title on hover (tooltip)
enableSmoothPositionAnimation	Animation Settings media player	Enable smooth position animation
showSuccessNotification	Notification Settings	Show notification on successful mod load
contextMenuIconOpacity	Context Menu Settings	Context menu icons opacity (0-100)
showRestartButton	Debug Settings	Show Restart Player in context menu

Two group headings were clobbered the same way: VisualizerFunctionsSettings now reads "Main Settings" instead of "Visualizer", and VisualizerStyleSettings reads "Appearance Settings" instead of "Visualizer Style".

4. The README is Chinese-first. User-facing text should default to English, with other languages provided through the localization syntax. The metadata is fine (@name / @description are English with :zh-CN variants), but the README body puts the full Chinese document first and the English one second — please swap them so the English version leads.

Related: the README claims "All settings ... fully translated to Simplified Chinese" / "全中文设置界面", but only $name was translated. There are 105 $description lines and 38 $options blocks in the file and zero $description:zh-CN or $options:zh-CN (compare: 36 $options:ru-RU). Either finish the translation or soften the claim.

5. Lyrics never appear if both "Show track title" and "Show track artist" are off. The lyric TextBlock is created at line 8832, nested inside if (g_settings.showTrackTitle || g_settings.showTrackArtist) at line 8653 — but the enclosing container is gated on hasText, which does include lxEnabled:

bool hasText = g_settings.showTrackTitle || g_settings.showTrackArtist || g_settings.lxEnabled;   // line 8350
...
if (hasText) {                                                    // 8616
    ...
    if (g_settings.showTrackTitle || g_settings.showTrackArtist) { // 8653
        ...
        if (g_settings.lxEnabled) {                                // 8832  <- lyric UI built here

So with lyrics enabled but title and artist both hidden, the text column is reserved and the player is made taller (line 8280), yet lyricElement stays null and nothing is ever drawn. Move the lxEnabled block out of the inner if, to the same level as it.

6. LyricColor() reads front() on a possibly-empty string. At line 3066:

if (!g_settings.lyricColor.empty()) {
    std::wstring s = g_settings.lyricColor;
    s.erase(0, s.find_first_not_of(L" \t"));
    s.erase(s.find_last_not_of(L" \t") + 1);
    if (s.front() == L'#') s.erase(s.begin());   // line 3073 - UB if s is now empty

If the setting contains only spaces/tabs, find_first_not_of returns npos, erase(0, npos) clears the string, and s.front() on an empty std::wstring is undefined behavior — inside explorer.exe. Add if (s.empty()) return ArtistColor(); after the trim (or use s.starts_with(L'#')).

7. The LX poller runs by default for every user, forever, and never backs off. lxEnabled defaults to true, and Wh_ModAfterInit unconditionally starts LxPollThreadProc, which every second creates a fresh WinHTTP session, opens a TCP connection to 127.0.0.1:23330, and tears it all down (lines 4910-5001). Anyone who installs this mod for the media player — the large majority, since LX Music is a niche prerequisite — pays for a connect attempt per second in explorer.exe in perpetuity, with nothing to show for it. Three concrete changes:

• Default lxEnabled to false, since the feature requires a third-party app that most users won't have.
• Hoist the WinHttpOpen session (and ideally the WinHttpConnect handle) out of the loop and reuse it; only the request handle needs to be per-poll.
• Back off when the endpoint is unreachable — e.g. after N consecutive failures, poll every 30 s until one succeeds. Right now a user with lyrics enabled and LX Music closed gets the full-rate loop indefinitely.

8. Please confirm the local-HTTP dependency with the maintainer before proceeding. Windhawk mods are expected to be self-contained and not to talk to servers; this one's headline feature is inoperative without LX Music Desktop running with its Open API enabled, and it makes HTTP requests from explorer.exe. The loopback restriction in LoadSettings (lines 2196-2202) is good and worth keeping, but the policy call on whether a mod may depend on another application's local HTTP API isn't mine to make — flag it explicitly in the PR description so it can be decided up front rather than after the rest of the work.

Optional improvements

Minor polish — none of this affects users in normal operation, so it's your call.

• LoadSettings() runs while the old LX thread is still reading g_settings. In Wh_ModSettingsChanged (line 11233) the order is LoadSettings(); StartLxThread();, and StartLxThread only stops the previous thread as its first act. During the LoadSettings() call the old poll thread can be in WinHttpConnect(hSession, g_settings.lxHost.c_str(), ...) (line 4922) while g_settings.lxHost is being reassigned on the settings thread — a std::wstring reallocation concurrent with a c_str() read is a use-after-free. Narrow window, but the fix is a one-line reorder:

  StopTimerThread();
  StopLxThread();     // <- before LoadSettings, matching how StopTimerThread is handled
  LoadSettings();
  StartLxThread();

• Unload and settings-apply can stall for seconds. StopLxThread() joins the poll thread, which may be inside LxFetchStatus with WinHttpSetTimeouts(hSession, 2000, 2000, 2000, 2000) — up to ~8 s worst case. In the normal "port closed" case the connect fails instantly, so this rarely bites, but if you keep a persistent session handle you can make the wait cancellable by calling WinHttpCloseHandle on it from the stop path before joining.

• Use WINHTTP_ACCESS_TYPE_NO_PROXY for a loopback endpoint (line 4916). WINHTTP_ACCESS_TYPE_DEFAULT_PROXY picks up the machine-wide WinHTTP proxy configuration, which has no business sitting between the mod and 127.0.0.1.

• Code comments are in Chinese (lines 2196, 3069, 3072, 3082, 3092, 4639, 4971, 8277, 8875, 8892, 8938, 9056, 10233, 10239, 10248). Every other mod in the repo comments in English; it makes the code reviewable and maintainable by others.

• enableMiniPlayerPopup may be redundant. The mini player only opens when the user binds the open_mini_player action to a click; a separate on/off switch that makes an explicitly bound action silently do nothing (line 3518) is a second place to look when it "stops working". Not binding the action already disables it.

• lyricShadowBlock is constructed unconditionally (line 8876) and then only parented when useShadowGrid is true — a wasted XAML object on every player rebuild. Move the TextBlock lyricShadowBlock; declaration inside the if (useShadowGrid).

Functionality notes

Non-critical observations and ideas about the lyrics feature itself.

• Lyric timing resolution is one poll interval (1 s). The displayed line only changes when a poll returns a new lyricLineText, so a line can appear up to a second late — very visible for lyrics. You already fetch the full LRC and progress, so you have everything needed to advance the line locally: record progress plus a GetTickCount64() stamp at each poll, and pick the current line from the parsed LRC on the UI tick instead of waiting for the server. That also makes the poll interval a bandwidth/CPU knob rather than an accuracy knob.

• The full LRC is re-parsed and re-sorted on every poll. ParseLrcLines (line 4853) splits the whole lyric text, allocates a std::wstring per line and std::sorts the result once per second even when the song hasn't changed. Cache the parsed vector keyed on the raw lyric string and only re-parse when it differs.

• LX Music's open API has a subscription endpoint. If the version you target exposes the server-sent-events subscribe-player-status route, using it would remove the polling loop entirely and give exact timing. Worth checking against the API docs.

• IsPureMusicLyric only recognizes the Chinese marker. Line 4960 matches 纯音乐 and nothing else, so the instrumental-track detection is a no-op for non-Chinese sources. Either make the marker list a setting, or note the limitation in the description.

• Player height is inflated whenever lyrics are enabled, even with no lyrics. Lines 8276-8282 raise phMin by the lyric row height whenever lxEnabled is set, regardless of whether a lyric is actually showing — including in collapse mode, whose whole point is to not reserve the row, and when LX Music isn't running at all. Consider recomputing the minimum height when the lyric visibility changes. Also note phMax is left alone, so a user whose "player max height" is below the new minimum gets a player taller than they configured (XAML MinHeight wins over MaxHeight).

• lyricsReplaceArtist causes layout jitter. With it on (the default), the artist row is hidden only while a lyric is available (line 10146), so the top row's content changes every time lyrics start/stop — between tracks, during instrumental sections, whenever a poll fails. Keeping the row reserved (or hiding the artist whenever lxEnabled regardless of lyric availability) would be steadier.

• lyricShadow is silently ignored while lyricsScroll is on. Both default to on for scrolling and off for shadow, so a user who enables the shadow sees no change and no explanation beyond the setting name. Consider disabling scrolling automatically when the shadow is requested, or noting it more prominently.

• Overlay visualizer skips column 0 even when there is no album art. Line 9061 sets the overlay's column from albumArtLeft alone; when showAlbumArt is false the album-art column is empty but the overlay still starts after it, leaving a strip of the player uncovered.

---

Next steps:

• /ai-review - after pushing fixes, to get a review of the updated code. You can repeat this as many times as you need, but each review is thorough and usually there's no need for more than 2-3 iterations.
• /ready-for-reviewer - once you're satisfied with the state of the pull request, to hand it over to a human reviewer. If some findings above are left unaddressed, add a short note explaining why.

See the review process for details.