LX Music Sync Server (Enhanced Edition)

Documentation | SyncServer | Changelog | 中文版

This project features a powerful built-in Web Player, allowing you to enjoy music anywhere in your browser. It also serves as an enhanced LX Music Data Sync Server.

✨ Web Player Key Features

1. Modern Interface

Featuring a clean, modern UI design with support for dark mode, providing a top-tier visual experience.

2. Multi-source Search

Supports aggregated searching across major music platforms, search and listen to anything you want.

3. Content & Playlists

Browse and search multi-platform playlists with ease. View comprehensive playlist details including covers, authors, and descriptions. Manage your playback queue with drag-and-drop sorting, batch operations, and quick positioning.

4. Powerful Playback Controls

Supports playback mode switching, sound quality selection, lyrics display, sleep timer, playback speed control, and more.

5. Cache Management

Features a fully automated caching system for lyrics, links, and song files, managed via a dedicated cache control panel for smooth playback even in weak network conditions.

6. Lyric Card Sharing

Introducing Lyric Card Sharing—generate stunning posters with customizable aspect ratios (Portrait/Landscape/Square), color styles (Dark/Light/Album colors), and line counts, with support for rotation and scaling.

7. Themes & System Configuration

Choose from multiple modern themes (Emerald, Deep Blue, Warm Sun, Nebula, Crimson) with automatic Light/Dark mode switching. Powerful system settings include auto-updating network playlists, automatic config backups, and multi-dimensional proxy support for seamless playback.

8. Custom Source Management

Supports importing custom source scripts to expand music sources even further.

9. Album & Artist Search & Collection

Search for albums and artists and favorite them with one click for quick access to your favorite music.

10. Subsonic Protocol & Global Search Support

Fully compatible with the Subsonic protocol, allowing you to use various Subsonic clients (e.g., Yinliu, Feishin, etc.) to connect and play music. Supports specifying platform prefixes such as wy:, kg:, tx:, kw:, mg:, or using online: / local: prefixes to force global online or local search within Subsonic clients.

11. Public Library & Shared Favorites

When "Enable Public Favorites and Songs" is enabled in the backend settings, all users (guests or different accounts) can share a common public music library and public playlists.

🔒 Access Control & Security

To protect your privacy, the Web Player supports password protection.

How to Enable

Environment Variable (Recommended for Docker users):
- ENABLE_WEBPLAYER_AUTH=true: Enable authentication
- WEBPLAYER_PASSWORD=yourpassword: Set access password
Web Interface: Log in to the management dashboard (default port 9527), go to "System Config", check "Enable Web Player Password" and set your password.

Permission & Custom Source Matrix (when `user.enablePublicRestriction` is enabled)

User Type	View List	Use/Toggle (Personal)	Change Default Quality	Upload/Import Public	Delete/Modify Public
Admin	✅ Allowed	✅ Allowed	✅ Allowed	✅ Allowed	✅ Allowed
Logged-in	✅ Allowed	✅ Allowed	✅ Allowed	❌ Denied	❌ Denied
Guest	❌ Hidden	❌ Denied	❌ Denied	❌ Denied	❌ Denied

📱 Mobile Adaptation

The Web Player is deeply optimized for mobile devices, providing a native App-like experience in mobile browsers.

🚀 Quick Start

Built with Node.js, supporting multiple deployment methods.

Option 1: Desktop Client

You can now run LX Music Sync Server more conveniently via our Desktop Client, available for Windows, macOS, and Linux.

📦 Download Latest: GitHub Releases
✨ Key Advantages:
- Single Window: Integrated management dashboard and Web player for a unified experience.
- System Tray: Minimizes to tray on close, ensuring the sync service stays active in the background.
- Port Conflict Resolution: Automatically detects and switches ports if the default is in use.
- Setup Wizard: Guided data path selection on first launch, supports Portable Mode.
- Multi-Arch Support: Builds for Windows (x64/x86/ARM64 Setup & Portable), macOS (Intel x64 & Apple Silicon arm64), and Linux (amd64/arm64/armv7l deb/AppImage).

Option 2: Containerized Deployment via Docker

This project supports pulling images from Docker Hub or GitHub Packages:

Docker Hub: xcq0607/lxserver:latest
GitHub Packages: ghcr.io/xcq0607/lxserver:latest

Docker Run Example:

docker run -d \
  -p 9527:9527 \
  -v $(pwd)/data:/server/data \
  -v $(pwd)/logs:/server/logs \
  -v $(pwd)/cache:/server/cache \
  -v $(pwd)/music:/server/music \
  --name lx-sync-server \
  --restart unless-stopped \
  xcq0607/lxserver:latest

Docker Compose Example:

Create a docker-compose.yml file:

version: '3'
services:
  lx-sync-server:
    image: xcq0607/lxserver:latest
    container_name: lx-sync-server
    restart: unless-stopped
    ports:
      - "9527:9527"
    volumes:
      - ./data:/server/data
      - ./logs:/server/logs
      - ./cache:/server/cache
      - ./music:/server/music
    environment:
      - NODE_ENV=production
      # - FRONTEND_PASSWORD=123456
      # - ENABLE_WEBPLAYER_AUTH=true
      # - WEBPLAYER_PASSWORD=yourpassword
      # - ADMIN_PATH=
      # - PLAYER_PATH=/music

Option 3: Manual Run (Git Clone)

# 1. Clone project
git clone https://github.com/XCQ0607/lxserver.git && cd lxserver

# 2. Install dependencies and build
npm ci && npm run build

# 3. Start service
npm start

Option 4: Using Release Build

Download the archive from GitHub Releases.
Extract and run npm install --production.
Execute npm start.

3. Access Info

Web Player: http://your-ip:9527/music (Default path, configurable via PLAYER_PATH)
Sync Dashboard: http://your-ip:9527 (Default path, configurable via ADMIN_PATH, default password: 123456)

🏗️ Architecture

Separated frontend and backend architecture based on Node.js:

Backend (Express + WebSocket): Core sync logic and WebDAV backup.
Console (Vanilla JS): Located in the root directory, handles user and data management.
WebPlayer (Vanilla JS): Handles music playback, default access path is /music.

🛠️ Configuration

Edit config.js directly. Environment variables take precedence:

Env Variable	Config Key	Description	Default
`PORT`	`port`	Service port	`9527`
`BIND_IP`	`bindIP`	Binding IP	`0.0.0.0`
`ADMIN_PATH`	`admin.path`	Backend management interface path	(empty)
`PLAYER_PATH`	`player.path`	Web player access path	`/music`
`SUBSONIC_ENABLE`	`subsonic.enable`	Enable Subsonic protocol support	`true`
`SUBSONIC_PATH`	`subsonic.path`	Subsonic access path	`/rest`
`FRONTEND_PASSWORD`	`frontend.password`	Web dashboard password	`123456`
`SERVER_NAME`	`serverName`	Sync service name	`lxserver`
`MAX_SNAPSHOT_NUM`	`maxSnapshotNum`	Max snapshots to keep	`10`
`CONFIG_PATH`	-	Absolute path to external config file	-
`DATA_PATH`	-	Absolute path to data storage directory	`./data`
`LOG_PATH`	-	Absolute path to log output directory	`./logs`
`PROXY_HEADER`	`proxy.header`	Proxy IP header (e.g., `x-real-ip`)	-
`USER_ENABLE_ROOT`	`user.enableRoot`	Enable root path (use `ip:port`, password must be unique)	`false`
`USER_ENABLE_PATH`	`user.enablePath`	Enable user path (use `ip:port/username`, passwords can repeat)	`true`
`WEBDAV_ENABLE`	`webdav.enable`	Enable WebDAV sync and backup	`false`
`WEBDAV_URL`	`webdav.url`	WebDAV URL	-
`WEBDAV_USERNAME`	`webdav.username`	WebDAV Username	-
`WEBDAV_PASSWORD`	`webdav.password`	WebDAV Password	-
`WEBDAV_SYNC_PATH`	`webdav.syncPath`	WebDAV remote sync path	`/lx-sync`
`WEBDAV_BACKUP_PATH`	`webdav.backupPath`	WebDAV remote backup path	`/lx-sync-backups`
`SYNC_INTERVAL`	`sync.interval`	WebDAV incremental sync interval (min)	`60`
`BACKUP_INTERVAL`	`sync.backupInterval`	WebDAV full backup interval (hours)	`24`
`ENABLE_WEBPLAYER_AUTH`	`player.enableAuth`	Enable Web Player password	`false`
`WEBPLAYER_PASSWORD`	`player.password`	Web Player password	`123456`
`DISABLE_TELEMETRY`	`disableTelemetry`	Disable anonymous telemetry and update notifications	`false`
`ENABLE_PUBLIC_USER_RESTRICTION`	`user.enablePublicRestriction`	Enable public user permission restriction (restrict upload/delete public sources)	`true`
`ENABLE_PUBLIC_NON_ADMIN_LOCAL_MUSIC`	`user.enablePublicNonAdminLocalMusic`	Enable non-admin access to local music (allows non-admin public accounts to access local music)	`false`
`ENABLE_PUBLIC_FAVORITES`	`user.enablePublicFavorites`	Enable public favorites and songs (allows guest/public to view and play public favorites)	`false`
`ENABLE_PUBLIC_NON_ADMIN_ACCESS`	`user.enablePublicNonAdminAccess`	Enable non-admin access to public favorites & songs (allows non-admin public accounts to view)	`false`
`ENABLE_LOGIN_USER_CACHE_RESTRICTION`	`user.enableLoginCacheRestriction`	Enable cache settings restriction for logged-in non-admin users	`false`
`ENABLE_CACHE_SIZE_LIMIT`	`user.enableCacheSizeLimit`	Enable cache size limit (auto-cleanup via LRU)	`false`
`CACHE_SIZE_LIMIT`	`user.cacheSizeLimit`	Cache size limit in MB	`2000`
`LIST_ADD_MUSIC_LOCATION_TYPE`	`list.addMusicLocationType`	Position when adding songs to list (`top` / `bottom`)	`top`
`PROXY_ALL_ENABLED`	`proxy.all.enabled`	Enable outgoing request proxy (for Music SDK)	`false`
`PROXY_ALL_ADDRESS`	`proxy.all.address`	Proxy address (supports http:// or socks5://)	-
`SINGER_SOURCE_PRIORITY`	`singer.sourcePriority`	Singer info retrieval priority (e.g., `tx,wy` or `wy,tx`)	`tx,wy`
`LX_USER_<username>`	`users` array	Quickly add a user, value is the password (e.g., `LX_USER_test=123`)	-

Advanced Config Items (`config.js` Only)

Some advanced options are only configurable by directly editing config.js:

Config Key	Description	Default
`subsonic.enableDebug`	Enable Subsonic debug log mode	`true`
`subsonic.onlineSearch`	Enable Subsonic online global search	`true`
`subsonic.onlineSearchMode`	Subsonic online search mode (`fallback` / `merge` / `local_only`)	`"fallback"`
`subsonic.onlineSearchSources`	Subsonic online search default platforms	`"wy,tx,kw,kg,mg"`
`subsonic.lyricTranslation`	Include translation in Subsonic lyrics	`true`
`artist.maxFetchPages`	Maximum fetch pages for artist songs	`20`
`cache.namingPattern`	Cache file naming rule (`simple` / `custom`)	`"simple"`
`system.allowUnsafeVM`	Allow VM mode custom source scripts (note security risks)	`false`

Note: The service currently supports two types of sync connection URLs: Root Path (URL configuration is ip:port) and User Path (URL configuration is ip:port/username). If the User Path is disabled, all sync user passwords must be completely unique.

🛡️ Data Collection & Privacy

Anonymous telemetry via PostHog is used for:

Bug Tracking: Version number and environment type.
Notifications: Update alerts and maintenance notices.

Totally Anonymous: No IP, username, or playlist content is collected.
How to Disable: Set DISABLE_TELEMETRY=true. Note: Disabling this prevents receiving update notifications.

🤝 Credits & Acknowledgements

Forked from lyswhut/lx-music-sync-server.
Web player logic inspired by lx-music-desktop.
API based on musicsdk.

👥 Contributors

📈 Star History

📄 License

This project is released under the Apache License 2.0. The following agreement is a supplement to the Apache License 2.0. In case of conflict, this agreement shall prevail.

Terminology: "This Project" refers to LX Music Web Player; "User" refers to the user who agrees to this agreement; "Official Music Platforms" refers to the collective official platforms of the music sources built into this project, including Kuwo, Kugou, Migu, etc.; "Copyrighted Data" refers to data owned by others, including but not limited to images, audio, names, etc.

I. Data Sources

Official Platforms: The online data from various official platforms in this project is pulled from their public servers. It is displayed after simple filtering and merging (the same as the data obtained from official apps in an unlogged state). Therefore, this project is not responsible for the legality or accuracy of the data.
Audio Data: This project itself does not have the ability to obtain specific audio data. The online audio data sources used come from the online links returned by the "Source" selected in the "Custom Source" settings. This project cannot verify its accuracy, and playback abnormalities may occur during use.
Other Data: Non-official platform data in this project (such as lists in "My List") comes from server-stored data. This project is not responsible for the legality or accuracy of this data.

II. Disclaimer

Copyrighted Data: Copyrighted data may be generated during the use of this project. This project does not own ownership of this copyrighted data. To avoid infringement, users must clear the copyrighted data generated during the use of this project within 24 hours.
Liability: Any direct, indirect, special, incidental, or consequential damages of any nature arising from this agreement or from the use or inability to use this project are the responsibility of the user.
Laws and Regulations: This project is completely free and open-sourced on GitHub for technical learning and exchange. Use of this project in violation of local laws and regulations is PROHIBITED. The user shall bear full responsibility for any illegal or non-compliant behavior caused by using this project, whether the user is aware of local laws and regulations or not.

III. Miscellaneous

Resource Usage: Some resources used in this project, including but not limited to fonts and images, come from the internet. If there is any infringement, please contact this project for removal.
Non-Commercial Nature: This project is only for technical feasibility exploration and research. It does not accept any commercial cooperation (including but not limited to advertising) or donations.
Acceptance of Agreement: If you use this project, it means you accept this agreement.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

LX Music Sync Server (Enhanced Edition)

✨ Web Player Key Features

1. Modern Interface

2. Multi-source Search

3. Content & Playlists

4. Powerful Playback Controls

5. Cache Management

6. Lyric Card Sharing

7. Themes & System Configuration

8. Custom Source Management

9. Album & Artist Search & Collection

10. Subsonic Protocol & Global Search Support

11. Public Library & Shared Favorites

🔒 Access Control & Security

How to Enable

Permission & Custom Source Matrix (when `user.enablePublicRestriction` is enabled)

📱 Mobile Adaptation

🚀 Quick Start

Option 1: Desktop Client

Option 2: Containerized Deployment via Docker

Option 3: Manual Run (Git Clone)

Option 4: Using Release Build

3. Access Info

🏗️ Architecture

🛠️ Configuration

Advanced Config Items (`config.js` Only)

🛡️ Data Collection & Privacy

🤝 Credits & Acknowledgements

👥 Contributors

📈 Star History

📄 License

I. Data Sources

II. Disclaimer

III. Miscellaneous

FilesExpand file tree

README_EN.md

Latest commit

History

README_EN.md

File metadata and controls

LX Music Sync Server (Enhanced Edition)

✨ Web Player Key Features

1. Modern Interface

2. Multi-source Search

3. Content & Playlists

4. Powerful Playback Controls

5. Cache Management

6. Lyric Card Sharing

7. Themes & System Configuration

8. Custom Source Management

9. Album & Artist Search & Collection

10. Subsonic Protocol & Global Search Support

11. Public Library & Shared Favorites

🔒 Access Control & Security

How to Enable

Permission & Custom Source Matrix (when user.enablePublicRestriction is enabled)

📱 Mobile Adaptation

🚀 Quick Start

Option 1: Desktop Client

Option 2: Containerized Deployment via Docker

Option 3: Manual Run (Git Clone)

Option 4: Using Release Build

3. Access Info

🏗️ Architecture

🛠️ Configuration

Advanced Config Items (config.js Only)

🛡️ Data Collection & Privacy

🤝 Credits & Acknowledgements

👥 Contributors

📈 Star History

📄 License

I. Data Sources

II. Disclaimer

III. Miscellaneous

Permission & Custom Source Matrix (when `user.enablePublicRestriction` is enabled)

Advanced Config Items (`config.js` Only)