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.

🔒 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.

📱 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 \
  --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
    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	`My Sync Server`
`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_URL`	`webdav.url`	WebDAV URL	-
`WEBDAV_USERNAME`	`webdav.username`	WebDAV Username	-
`WEBDAV_PASSWORD`	`webdav.password`	WebDAV Password	-
`SYNC_INTERVAL`	`sync.interval`	WebDAV auto-backup interval (min)	`60`
`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`
`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://)	-
`LX_USER_<username>`	`users` array	Quickly add a user, value is the password (e.g., `LX_USER_test=123`)	-

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.

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

🔒 Access Control & Security

How to Enable

📱 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

🛡️ Data Collection & Privacy

🤝 Credits & Acknowledgements

📄 License

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

🔒 Access Control & Security

How to Enable

📱 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

🛡️ Data Collection & Privacy

🤝 Credits & Acknowledgements

📄 License