# 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"?](#what-is-a-source-the-most-important-concept).
---
## 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:
```text
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:
| Setting | Where | What it controls |
|---------|-------|------------------|
| **Interface source** (接口源 / `common.apiSource`) | Settings → Music Source | Which backend resolves playback URLs and assists search. Defaults to the built-in `temp` interface. |
| **Custom source** (自定义源) | Settings → Custom Source | A user-supplied JavaScript file that resolves playback URLs for one or more platforms. |
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](#5-common-tasks); the full scripting reference lives in the Admin & Developer Guide.
---
## 3. Installation
### 3.1 System requirements
| Requirement | Detail |
|-------------|--------|
| Operating system | Windows 7 and above, macOS, or Linux |
| Architecture | x64, x86 (32-bit), and ARM64 builds are published |
| Windows 7 extras | Aero theme recommended (transparent windows); `.NET Framework 4.7.1`+ may be needed if the window will not display; PowerShell 5.1+ for desktop-lyric font lists |
| Disk | A few hundred MB plus space for downloads and cached lyrics |
### 3.2 Choosing the right download
The Releases page offers several file types. Match the file name to your system:
| File name contains | Platform / type |
|--------------------|-----------------|
| `win_` … `Setup` | Windows installer — **supports auto-update** |
| `win_` … `green` | Windows portable / 7z — no install, **no auto-update** |
| `.dmg` | macOS |
| `.AppImage`, `.deb`, `.rpm`, `.pacman` | Linux |
| `x64` | 64-bit |
| `x86` | 32-bit |
| `arm` / `arm64` | ARM architecture |
| both `x64` and `x86` (集合版) | Combined build; the installer picks the right one for 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:
| Platform | Location |
|----------|----------|
| Windows | `%APPDATA%/lx-music-desktop` |
| Linux | `$XDG_CONFIG_HOME/lx-music-desktop` or `~/.config/lx-music-desktop` |
| macOS | `~/Library/Application Support/lx-music-desktop` |
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](#6-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](#6-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://: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.:
```bash
curl http://127.0.0.1:23330/status
```
```json
{"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:
```text
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:
```bash
./lx-music-desktop -search="突然的自我 - 伍佰"
```
```bash
./lx-music-desktop -play="type=songList&source=myList&name=默认列表&index=2"
```
The full startup-parameter reference is in [Section 7](#7-startup-parameters).
### 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.
| Action | Default (in-app) | Default (global) |
|--------|------------------|------------------|
| Play / pause | Ctrl+F5 | Ctrl+Alt+F5 |
| Previous track | Ctrl+← | Ctrl+Alt+← |
| Next track | Ctrl+→ | Ctrl+Alt+→ |
| Volume up | — | Ctrl+Alt+↑ |
| Volume down | — | Ctrl+Alt+↓ |
| Focus search box | F1 | — |
| Toggle desktop lyrics | — | Ctrl+Alt+0 |
| Lock desktop lyrics | — | Ctrl+Alt+- |
| Toggle lyrics always-on-top | — | Ctrl+Alt+= |
> [!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.
```bash
./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](#34-where-your-data-is-stored)), 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:
```bash
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.
```text
.\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`+.
```text
.\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](https://github.com/lyswhut/lx-music-desktop/issues/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](https://github.com/lyswhut/lx-music-desktop/issues/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](https://github.com/lyswhut/lx-music-desktop/issues/2842), [#2834](https://github.com/lyswhut/lx-music-desktop/issues/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.
| Parameter | Since | Effect |
|-----------|-------|--------|
| `-search=""` | — | Search the given text on launch, e.g. `-search="突然的自我 - 伍佰"` |
| `-dha` | v1.6.0 | Disable hardware acceleration (fixes some display/transparency issues) |
| `-dt` | v1.6.0 | Run with a non-transparent window (for Windows 7 without Aero). Renamed from `-nt`. Does not affect desktop lyrics |
| `-dhmkh` | v1.9.0 | Disable Chromium hardware media-key handling |
| `-proxy-server=""` | v1.17.0 | Proxy all app traffic (no auth). In-app interface proxy takes priority for interface requests |
| `-proxy-bypass-list=""` | v1.17.0 | Semicolon-separated hosts to bypass the proxy; only meaningful with `-proxy-server` |
| `-play="type=songList&source=&..."` | — | Play a list on launch (see below) |
| `--disable-gpu-sandbox`, `--no-sandbox`, `--disable-gpu` | — | Chromium flags for stubborn display problems |
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)
```bash
./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](#34-where-your-data-is-stored)). 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.
---
_Generated June 2026 from lyswhut/lx-music-desktop at 9c364b4. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._