LX Music Desktop User Guide

LX Music Desktop (洛雪音乐助手 桌面版) is a free, open-source music search assistant for Windows, macOS, and Linux, built with Electron and Vue 3. It lets you search and audition tracks across several major Chinese music platforms — Kuwo, Kugou, QQ Music, NetEase Cloud Music, and Migu — from a single window, organize them into local playlists, view leaderboards, download tracks, and show synchronized desktop lyrics.

Important

LX Music does not host, own, or provide any audio itself. It sends the song name, artist, and platform you choose to a music source ("源"), and that source returns a playback URL. With no working source configured, search results appear but tracks will not play or download. Understanding sources is the single most important concept in this guide — see What Is a "Source"?.

1. Quick Start

What LX Music is (and is not)

LX Music began life — and is still primarily designed — as a tool to find music, not as your everyday media player. Its playback feature is intended for auditioning tracks. The default settings and UI deliberately favor capability over hand-holding, so it pays to walk through Settings once before serious use.

Key features:

• Unified search across Kuwo (酷我), Kugou (酷狗), QQ Music (QQ音乐), NetEase Cloud Music (网易云), and Migu (咪咕)
• Local playlists ("My List" / 我的列表) with favorites, multi-select, drag reordering, and import/export
• Online song lists (歌单) and platform leaderboards (排行榜)
• Track downloads with embedded cover art and lyrics
• Desktop lyrics window (horizontal or vertical), plus play-detail scrolling lyrics
• Custom user sources (自定义源) — drop-in JavaScript scripts that resolve playback URLs
• Cross-device list sync over your local network, an Open API for third-party control, and lxmusic:// scheme URLs
• A built-in equalizer, audio effects, theming, and global/local hotkeys

Prerequisites

A Windows 7+ , macOS, or Linux desktop. No account or sign-up is required to install or use the app.

Install (recommended method)

Download the installer for your platform from the official GitHub Releases page and run it:

https://github.com/lyswhut/lx-music-desktop/releases

On Windows, pick the Setup (安装版) build — it supports automatic updates.

Tip

The only official download location is GitHub Releases. Any other site, app store, or網盘 mirror is a third-party repost and is not affiliated with the project. When in doubt, verify the link against the project homepage.

Your first search

1. Launch LX Music.
2. Type a song or artist into the search box at the top and press Enter.
3. Pick a platform tab (e.g. 酷我 / Kuwo) if you want results from a specific source.
4. Double-click a result to audition it, or select several tracks and add them to a list.

If results appear but nothing plays, your source needs attention — read the next section.

2. What Is a "Source"? (The Most Important Concept)

LX Music separates the catalog (song names, artists, albums, leaderboards — pulled from each platform's public data) from the playback URL (the actual audio link). The app can show you the catalog on its own, but it cannot produce a playable audio link by itself. That job belongs to a source.

There are two kinds of source settings, and they do different things:

The default temp interface works out of the box but depends on a shared community endpoint that can be rate-limited or temporarily unavailable. If most or all tracks fail to play, switching the interface source or importing a custom source is the fix.

Note

Because LX Music never verifies that a returned URL is the "correct" audio, you may occasionally hear a track that does not match the title, or get a track that will not play. This is inherent to how aggregated sources work — switch the song or source and try again.

Caution

A custom source is arbitrary JavaScript that runs with full access inside the app. Only import custom-source scripts from authors you trust. A malicious script could abuse your network or local data. See the Admin & Developer Guide for the trust model and the scripting API.

Writing or importing a custom source is covered under Common Tasks; the full scripting reference lives in the Admin & Developer Guide.

3. Installation

3.1 System requirements

3.2 Choosing the right download

The Releases page offers several file types. Match the file name to your system:

Important

macOS and Linux builds, and the Windows green/portable build, do not support automatic updates. To update these, download the newest release and reinstall or overwrite manually.

3.3 Platform install steps

Windows

1. Download the Setup build for your architecture.
2. Run the installer. When prompted, choose Install for current user (为当前用户安装) and a location that does not require administrator rights.
3. Launch from the Start menu or desktop shortcut.

macOS

1. Download the .dmg matching your chip (Intel x64 or Apple Silicon arm64).
2. Drag LX Music into Applications.
3. If macOS reports the app is "damaged" (已损坏), clear the quarantine flag (see Troubleshooting).

Linux

1. Download the package for your distro: .deb (Debian/Ubuntu), .rpm (Fedora/RHEL), .pacman (Arch), or the portable .AppImage.
2. Install with your package manager, e.g. sudo dpkg -i lx-music-desktop_*.deb, or mark the AppImage executable and run it.

Tip

On Windows, installing as administrator but then running normally can cause a later uninstall to leave the app un-reinstallable. Installing for the current user avoids this entirely.

3.4 Where your data is stored

LX Music keeps all configuration, playlists, lyrics cache, and the database in a per-user data directory:

On Windows, if a folder named portable exists next to the executable, LX Music stores all data inside it instead — turning any install into a portable one (available since v1.17.0).

Note

The core list database lives at LxDatas/lx.data.db inside that data directory. Back it up before experimenting with the sync feature.

3.5 Verifying the install

Launch the app, run a search, and audition any track. If the track plays, your install and default source are working. If search returns results but playback fails everywhere, jump to Troubleshooting.

4. Core Usage

LX Music's window is frameless and organized around a left-hand navigation rail. The main areas are Search, My List, Leaderboard, Song Lists, and the Play Bar / Play Detail at the bottom. This section is organized by what you'll actually do.

4.1 Searching for music

1. Click the search box (or press F1 to focus it from anywhere).
2. Type a song title, artist, or both, then press Enter.
3. Use the source tabs to filter results by platform, or the combined view to see all.

While typing, you can move through search suggestions with the ↑/↓ arrow keys and press Enter to search the highlighted suggestion.

Tip

Right-click inside the search box to paste the current clipboard text. Right-click a single search-history entry to remove just that entry.

4.2 The playlist mechanism (read this once)

LX Music's playback model is list-driven and is the part most new users stumble on:

• Playing a track from a search, song-list, or leaderboard view first adds it to your "试听" (audition) list under My List, then plays it from there. Playing one search result is equivalent to adding it and pressing play.
• To play multiple tracks, multi-select them (see below) and either add them to a list and play that list, or use Play Later (稍后播放).
• For a song-list detail page, you can also press the play button at the top to temporarily play the whole list, or collect (收藏) the list into My List and play it from there.
• For a leaderboard, right-click the leaderboard's name for a menu to play or collect the entire board.
• Play Later tracks go into a special highest-priority queue: pressing Next consumes them, but Previous cannot return to a Play-Later track. Changing songs by any means other than Next/Previous clears the Play-Later queue.

Note

There is an optional setting, "double-click a list item to switch to that list and play" (off by default), which only applies to song lists and leaderboards.

4.3 Multi-selecting tracks

Multi-select needs a modifier key (since v0.18.0):

• Range: hold Shift, click the first item, then click the last.
• Individual: hold Ctrl (Command on macOS) and click each item.
• Select all: hold Ctrl and press A.
• Clicking an unselected item adds it; clicking a selected item removes it. Click any item without a modifier to clear the selection.

After selecting, right-click for the context menu to act on the chosen tracks (add to list, download, play later, etc.).

4.4 Playing and controlling audio

The play bar at the bottom controls playback. From it you can:

• Play/pause, previous, next, and adjust volume
• Switch the loop mode (list loop, single loop, random, sequential)
• Open Play Detail for full-window scrolling lyrics
• Toggle the desktop lyrics window with the LRC button on the progress bar

Tip

Right-click the cover image on the play bar to jump to ("locate") the currently playing track in its list. Right-click the LRC button on the progress bar to lock/unlock the desktop lyrics window. Left-click the song name on the play bar to copy it.

4.5 My List — local playlists

My List (我的列表) is where your own playlists live, including the built-in Default (默认列表), Love (我的收藏 / favorites), and the audition list.

• Create a list: use the new-list button in My List.
• Add tracks: multi-select in any view → right-click → add to a list.
• Favorite a track: use the heart/collect control on the play bar or context menu.
• Search within a list: with a list open, press Ctrl+F. In that box, ↑/↓ selects, Enter jumps to the track, Ctrl+Enter jumps and plays, and Esc closes the box.
• Reorder lists: hold Ctrl (Command on macOS) to enter drag mode, then drag a list to a new position.
• Rename a list: double-click the name to edit; press Esc to cancel.

Tip

When adding the same track(s) to several lists, hold Ctrl while clicking each target list name — the add dialog stays open instead of closing after the first pick (since v1.22.0).

4.6 Song lists (歌单)

The Song List view browses curated playlists from each platform, and can open a shared playlist directly.

• Switch the song-list source with the selector at the top-right; you cannot open a list across sources, so the source must match the list's platform.
• Open a shared list by pasting its URL, or by entering its numeric ID directly.
• Collect a list (收藏) to keep a local copy under My List. Right-click a collected list name → Update to overwrite the local copy with the latest online version.

Note

NetEase's "我喜欢" (My Favorites) list requires login. To open it you must append ### and a valid token to the list ID/URL, e.g. 11332###yourtoken. The token is the MUSIC_U cookie value from a logged-in browser session. Treat this token as a secret.

4.7 Leaderboards (排行榜)

The Leaderboard view shows each platform's charts. Select a source and a board to browse it; right-click a board name to play or collect the whole board at once (since v1.10.0).

4.8 Downloading music

Downloads are off by default — enable them in Settings → Download first. Once enabled:

1. Multi-select tracks (or use a track's context menu).
2. Choose Download, then pick a quality.
3. Track progress in the Download view.

Available qualities depend on the track and source, drawn from: flac24bit, flac, wav, ape, 320k, 192k, 128k.

Important

Set a download folder you have write permission to. A folder without write access produces ENOENT: no such file or directory, mkdir — see Troubleshooting.

Download behavior is configurable: file-name template (default 歌名 - 歌手), grouping downloads into per-list subfolders, max concurrent downloads (default 3), skipping existing files, embedding cover art, and embedding lyrics (including LX-format .lxlrc).

4.9 Desktop lyrics

The desktop lyrics window floats synchronized lyrics over your desktop.

• Toggle it from the play bar's LRC button, the tray menu, or a hotkey.
• Lock it (锁定) to click through it; unlock to move and resize it.
• Choose horizontal or vertical orientation, font, size, colors, opacity, and alignment in Settings → Desktop Lyrics.

Note

On Windows 7 without Aero, and on some Linux setups, the transparent lyric window can misbehave — see Troubleshooting for -dt and -dha startup options.

4.10 Themes and the play detail page

• Themes: Settings → Theme. Pick a built-in theme or create your own; the default is green. The special Auto (道法自然) theme follows your system light/dark mode — right-click it to set distinct light and dark themes.
• Play Detail: the full-window lyric view, with translation and romanization toggles, adjustable font size, and alignment.

Tip

A festive Happy New Year theme is applied automatically during January and February.

5. Common Tasks

Recipes for the things people most often want to do. Each lists the goal, steps, and what to check if it fails.

5.1 Switch the interface source when nothing plays

Goal: restore playback when every track fails.

1. Open Settings → Music Source.
2. Switch 接口源 (interface source) from temp to another available option.
3. Return and re-audition a track.

If it fails: the issue may be your network rather than the source — see Troubleshooting.

5.2 Import a custom source

Goal: use a community or self-written source script to resolve playback URLs.

1. Obtain a .js source file from a trusted author.
2. Open Settings → Custom Source (自定义源).
3. Import the script and enable it.
4. Audition a track to confirm it resolves.

Caution

Importing a source runs its code with full privileges. Never import a script you cannot read or do not trust.

5.3 Build and play a playlist

Goal: play several specific tracks in order.

1. Search or browse for the tracks.
2. Multi-select them (Shift/Ctrl + click).
3. Right-click → Add to list → choose or create a list.
4. Open that list under My List and play it.

5.4 Download an album or list with cover art and lyrics

1. Enable downloads in Settings → Download and pick a writable folder.
2. Turn on embed cover and the lyric-embed options you want.
3. Multi-select the tracks, right-click → Download, choose a quality.
4. Watch the Download view for completion.

5.5 Sync your lists to a phone over the LAN

Goal: keep My List in sync between this PC and the LX Music mobile app.

1. Put both devices on the same router/network (no AP isolation).
2. On the PC: Settings → Data Sync → enable sync. Allow the firewall/network prompt if it appears.
3. On the phone: enter the sync server address shown on the PC (choose the one most similar to the phone's own LAN address) and the matching port (default 23332), then press Enter to commit, and start sync.
4. On first sync, if both sides have non-empty lists, the PC shows a merge-mode dialog — pick how to reconcile them.

Warning

Sync data is transmitted in plain text. Only use it on a trusted network. Back up your lists before the first sync.

If it fails: confirm both devices are on the same router, the PC firewall isn't blocking the sync port, and AP isolation is off. Test by opening http://<pc-sync-address>:23332/hello from the phone's browser — a working link shows Hello~::^-^::.

5.6 Control playback from another app (Open API)

Goal: let a third-party tool read player status and send commands.

1. Settings → Open API → enable it (default port 23330).
2. Leave bind LAN off to keep it on 127.0.0.1 only, or turn it on to expose it to your local network.
3. Send HTTP GET requests, e.g.:

curl http://127.0.0.1:23330/status

{"status":"playing","name":"突然的自我","singer":"伍佰","albumName":"...","lyricLineText":"...","duration":235,"progress":42,"playbackRate":1}

The full endpoint list (play, pause, skip, seek, volume, mute, lyrics, and an SSE status stream) is in the Admin & Developer Guide.

Caution

The Open API has no authentication and sends Access-Control-Allow-Origin: *. Enabling bind LAN lets anyone on your network control playback. Keep it bound to localhost unless you specifically need remote control.

5.7 Launch and control LX Music from a browser (Scheme URL)

LX Music registers the lxmusic:// URL scheme (since v1.17.0), so links can drive it. A companion userscript wires this into music websites. Examples:

lxmusic://music/search/kw/突然的自我
lxmusic://songlist/open/kw/123456

The complete scheme-URL parameter tables are in the Admin & Developer Guide.

5.8 Start LX Music with a search or a specific list

Use startup parameters from a shortcut or terminal:

./lx-music-desktop -search="突然的自我 - 伍佰"

./lx-music-desktop -play="type=songList&source=myList&name=默认列表&index=2"

The full startup-parameter reference is in Section 7.

5.9 Set up global media hotkeys

1. Settings → Hotkeys.
2. Enable global hotkeys (off by default) and assign keys, or use the built-in defaults below.

Note

On macOS, Ctrl in these shortcuts corresponds to Command. In-app (local) hotkeys only fire while LX Music is focused; global hotkeys work system-wide but are disabled until you turn them on.

5.10 Use a proxy

Two proxy scopes exist:

• In-app proxy (Settings → Network → Proxy): proxies only the music-interface requests. Higher priority for interface traffic.
• Process proxy (-proxy-server startup parameter): proxies all of the app's traffic. Does not affect in-app interface requests.

./lx-music-desktop -proxy-server="127.0.0.1:1081"

5.11 Make a portable Windows install

Create an empty folder named portable next to lx-music-desktop.exe. On next launch, all data is stored there, so you can move the whole folder between machines.

5.12 Back up and restore your lists

1. Close LX Music.
2. Copy the data directory (see Section 3.4), especially LxDatas/lx.data.db.
3. To restore, put the files back before launching.

Tip

Do this before your first sync and before any major version upgrade.

6. Troubleshooting

A quick decision path: search returns nothing → network/proxy or all-source outage. Search works but playback fails → source/network. UI won't display → GPU/transparency startup flags. Sync won't connect → same-network/firewall.

Error: 请求异常😮，可以多试几次，若还是不行就换一首吧。。。

Cause: the music interface could not be reached, often a transient network or shared-endpoint issue.

Solution:

1. Try a different network (e.g. switch to mobile hotspot); toggling airplane mode on a phone hotspot can help.
2. On home broadband, power-cycle the modem/ONT for ~5 minutes.
3. Settings → Music Source → switch the interface source.
4. Retry a different song.

Prevention: keep the app updated and avoid overloaded networks.

Error: getaddrinfo EAI_AGAIN ... or 无法连接到服务器

Cause: DNS resolution failure reaching the interface server.

Solution:

1. Open http://ts.tempmusics.tk in a browser — a 404 is normal and means the network can reach it. Anything else means your network can't.
2. If it won't load, set DNS to automatic, or set it manually to 223.6.6.6 or 8.8.8.8 (avoid 360 DNS). Flush the DNS cache and restart the app.

Prevention: use a reliable DNS resolver.

Error: 音频加载错误，5秒后切换下一首 (Windows)

Cause: a system proxy is interfering with audio loading.

Solution: open inetcpl.cpl (Win+R), go to Connections → LAN settings, and uncheck the proxy server (and "automatically detect settings"), then confirm.

Prevention: keep system LAN proxy settings clean.

Error: ENOENT: no such file or directory, mkdir

Cause: the download folder is not writable.

Solution: change the download directory (Settings → Download) to a folder you have write permission to.

Prevention: avoid system-protected paths for downloads.

Issue: macOS reports "lx-music-desktop 已损坏" / cannot open

Cause: the app is unsigned and Gatekeeper quarantines it.

Solution: run in Terminal:

sudo xattr -rd com.apple.quarantine /Applications/lx-music-desktop.app

Prevention: expect this on every unsigned macOS build; re-run after updates if needed.

Issue: Windows 10/11 window is blank, incomplete, or invisible

Cause: GPU/sandbox or transparency rendering problems.

Solution: launch with --disable-gpu-sandbox. If that fails, try one at a time: --no-sandbox, -dha, --disable-gpu. As a last resort, install the app to a different folder.

.\lx-music-desktop.exe --disable-gpu-sandbox

Caution

These flags disable security or performance features. Don't use them unless you actually have a display problem.

Issue: Windows 7 window displays abnormally

Cause: transparent windows require DWM/Aero on Windows 7.

Solution: enable the Aero theme, or run with -dt to use a non-transparent window. If the UI still won't show, install .NET Framework 4.7.1+.

.\lx-music-desktop.exe -dt

Prevention: keep Aero enabled on Windows 7.

Issue: Linux window transparency artifacts

Cause: Electron transparency issues on some Linux compositors.

Solution: launch with -dha to disable hardware acceleration (supported since v1.6.0).

Issue: Desktop lyrics off-screen or not centered

Cause: a known positioning bug on some setups (e.g. issue #2776); macOS may leave a residual shadow (an upstream Electron bug).

Solution: unlock the lyric window and reposition it; adjust alignment in Settings → Desktop Lyrics. On Windows 7, ensure Aero is on.

Issue: Desktop-lyric font list is empty (Windows 7)

Cause: font enumeration needs PowerShell 5.1+.

Solution: install PowerShell 5.1 or newer (check with Get-Host).

Issue: Whole app cannot connect (search, leaderboards, lists all fail)

Cause: misconfigured in-app proxy, or a firewall/security tool blocking the app.

Solution: check Settings → Network for a bad proxy setting; allow LX Music through your firewall.

Issue: Cannot open an external/shared song list

Cause: the list's platform doesn't match the selected song-list source, or the share link can't be parsed.

Solution: switch the song-list source to match the list's platform. For shared links that fail, open the link in a browser first, then copy the address back; or enter the list ID directly.

Issue: Antivirus flags LX Music (火绒报毒 / virus warning)

Cause: unsigned binaries and use of MediaDevices.enumerateDevices() (for audio-output switching, since v0.17.0) can trigger heuristic or "camera access" warnings. The camera is never actually used.

Solution: if you downloaded from the official Releases page (or built from source), this is a false positive. You may deny the camera prompt safely. Ultimately, decide for yourself whether to continue.

Prevention: only download from the official link; builds are produced by public CI from open source.

Issue: Windows install fails ("安装程序并未成功地运行完成")

Cause: leftover files or registry entries from previous installs, or multiple versions in different paths.

Solution: uninstall all existing versions via Programs & Features, clean leftover install-path files, clean the registry with a cleanup tool, then reinstall.

Issue: Missing xxx.dll

Cause: missing system libraries.

Solution: open an admin cmd, run sfc /scannow, and reboot. If it persists, search the exact error message for the specific DLL fix.

Issue: Headphones unexpectedly power off

Cause: a reported incompatibility with certain Edifier headphone models (issue #457).

Solution: launch with -dhmkh to disable Chromium's hardware media-key handling.

Issue: List order wrong or new tracks disappear after restart

Cause: reported list-persistence bugs on some setups (e.g. issues #2842, #2834).

Solution: ensure the app closes cleanly (don't kill it mid-write); keep a backup of lx.data.db. Report reproducible cases upstream.

7. Startup Parameters

Add these to a desktop shortcut or run from a terminal.

The -play parameter accepts:

• type — currently fixed to songList
• source — kw, kg, tx, wy, mg (online), or myList (local)
• link — online list URL or ID (required for online sources; URL-encode a URL)
• name — local list name (required when source=myList)
• index — zero-based start position (optional)

./lx-music-desktop -play="type=songList&source=myList&name=默认列表&index=2"

Note

Source codes map to platforms as: kw Kuwo, kg Kugou, tx QQ Music, wy NetEase, mg Migu.

8. FAQ

Q: Why doesn't anything play even though search works?

Playback depends on a source returning a URL. Switch the interface source (Settings → Music Source) or import a trusted custom source. If it's everywhere and persistent, it may be a network/DNS issue — see Troubleshooting.

Q: Is LX Music a full music player?

Not by design. It's primarily a tool to find music; playback is for auditioning. Many people use it as a player anyway, but the defaults and UI prioritize discovery over a polished player experience.

Q: Which platforms can I search?

Kuwo (酷我), Kugou (酷狗), QQ Music (腾讯), NetEase Cloud Music (网易云), and Migu (咪咕). A Baidu adapter also exists in the codebase. Actual availability depends on your interface/custom source.

Q: How do I update the app?

Windows Setup builds auto-update on launch (the download resumes next launch if interrupted). Windows green/portable, macOS, and Linux builds do not auto-update — download and reinstall manually. If auto-update fails, it's usually a GitHub-access problem; update by hand.

Q: Where are my playlists and settings stored?

In the per-user data directory for your OS (see Section 3.4). The list database is LxDatas/lx.data.db.

Q: How do I make a portable install?

Create a portable folder next to the Windows executable; all data then lives there.

Q: How do I reset settings to defaults?

Close the app and remove (or move aside) the configuration in the data directory, then relaunch — defaults regenerate. Back up first if you want to keep your lists.

Q: How do I play NetEase's "我喜欢" list?

It needs login. Append ### plus your MUSIC_U cookie token to the list ID/URL, e.g. 11332###yourtoken. Keep the token private.

Q: Can I control LX Music from scripts or other apps?

Yes — enable the Open API (Settings → Open API, default port 23330) for HTTP control, or use lxmusic:// scheme URLs. Both are documented in the Admin & Developer Guide.

Q: Can I sync lists with my phone?

Yes, over the same LAN (default port 23332). Sync is experimental and transmits in plain text — use it on a trusted network and back up first. A standalone sync server project also exists for always-on, multi-device sync.

Q: Why does my antivirus complain, and why a camera prompt?

Unsigned binaries trigger heuristics; the audio-output-device feature calls a browser API that some security tools misread as camera access. The camera is never used. Download only from the official link.

Q: Can I change the audio quality?

Yes — set playback quality in Settings and choose a quality per download. Options include flac24bit, flac, 320k, 192k, 128k (availability varies by track/source).

Q: Does it have an equalizer?

Yes — a 10-band equalizer plus convolution reverb, a stereo panner, and a pitch shifter live under the audio/sound-effect settings.

Q: What's the difference between the in-app proxy and -proxy-server?

The in-app proxy (Settings → Network) only affects music-interface requests and takes priority for them. -proxy-server proxies all app traffic but not the in-app interface requests.

Q: Why are some downloaded tracks misnamed or wrong?

Sources return URLs that LX Music can't verify; occasionally a returned URL doesn't match the requested track. Switch source or song and retry.

Q: Is there a mobile version?

Yes — LX Music Mobile is a separate project at github.com/lyswhut/lx-music-mobile, and it's the sync counterpart for the LAN sync feature.