LX Music Desktop

lx-music-desktop uses a specific logic for handling playlists:

1. Automatic Addition: By default, playing a song from a search result, playlist, or ranking list automatically adds that song to your "My List" (试听列表) before playing. This is equivalent to manually adding it first.
2. Playing Multiple Songs: To play multiple songs from a list, use the multi-select feature (see Multi-select guide) to select songs, then add them to "My List" or use the "Play Later" (稍后播放) function.
3. Playlist/Ranking Details:
   • For Playlists: Click the play button on the detail page for temporary playback, or click "Favorite" (收藏) to add it to "My List".
   • For Rankings: Right-click the ranking name to access a menu with options to play or favorite the entire ranking.
4. Play Later (稍后播放) Queue: Songs added here enter a high-priority special queue. Clicking "Next Track" consumes this queue. Note that you cannot use "Previous Track" to go back into this queue, and the queue is cleared if you switch songs by directly clicking a song in a list rather than using the playback controls.
5. Automatic List Switching: Since v1.18.0, there is a setting (disabled by default) that automatically switches to the current list when double-clicking a song in a list. This applies to playlists and rankings.

The synchronization feature allows real-time song list synchronization between the PC and mobile versions when they are on the same local network (LAN).

Warning: Data is transmitted in plaintext. Use this feature only on trusted networks.

Setup Steps:

1. On PC: Go to Settings -> Data Sync and enable the synchronization function. Allow any firewall/security software prompts.
2. On Mobile: Go to Settings -> Sync. In the Sync Server Address field, enter the address displayed on the PC. If multiple addresses are shown, choose the one most similar to the mobile device's local IP. Ensure the port matches the PC's sync port. Press Enter after typing to make the input effective.
3. On Mobile: Tap Start Sync.
4. First-time Sync: If both devices have existing lists, the PC will prompt you to choose a synchronization method. Subsequent syncs will automatically merge changes from both devices.

Troubleshooting Connection Failures:

• Ensure both devices are on the same router/network.
• Check if a firewall is blocking the PC's service port.
• Ensure the router does not have AP Isolation enabled.
• Verification: Open a mobile browser and navigate to http://[PC_IP_ADDRESS]:[PORT]/hello (e.g., http://192.168.1.5:23332/hello). If it displays Hello~::^-^::, the network connection is working.

http://x.x.x.x:23332/hello

Mouse Operations

• Locate Current Song: Right-click the song cover in the playback bar.
• Lock/Unlock Desktop Lyrics: Right-click the LRC button on the playback bar progress bar.
• Paste Text: Right-click inside the search box or playlist URL input box to paste clipboard content.
• Remove Search History: Right-click a single entry in the search history.
• Copy Text: Select text within a song list (search, playlist, ranking, or My List) and right-click to copy.
• Close Playback Details: Double-click the right mouse button within the playback details page.
• Copy Song Name: Left-click the song name in the playback bar.
• Theme Settings: Right-click the "Dao Fa Zi Ran (Auto)" theme in Settings -> Theme Settings to open light/dark mode settings.

Keyboard Operations

• Search/Selection: Use Up/Down arrows to navigate search candidates; press Enter to select.
• Navigation: Press Backspace in a playlist detail page to return to the list.
• Multi-select: Use Ctrl or Shift (on macOS, use Command) to select multiple items in a list.
• My List Search: Press Ctrl + f to open the search box within "My List".
  • Esc: Close search box.
  • Up/Down: Navigate songs.
  • Enter: Jump to selected song.
  • Ctrl + Enter: Jump to and play the selected song.
• Reorder My List: Hold Ctrl (or Command on macOS) to enter "Drag Mode", then drag list items to reorder.
• Edit List Name: Press Esc to cancel editing.
• Full Screen: Press F11 to toggle full screen.
• Batch Add to Lists: In the "Add Song" popup, hold Ctrl while clicking a list name to prevent the window from closing, allowing you to add the same batch of songs to multiple lists.

Custom music sources are written in JavaScript (ES6+ supported) using UTF-8 encoding. The script interacts with the application via an event-based system using the window.lx API.

To create a source, you must:

1. Include a specific JSDoc comment block at the top of the file for metadata.
2. Register for the EVENT_NAMES.request event to handle music URL requests.
3. Send the EVENT_NAMES.inited event to notify the application that the script is ready and to define supported sources and qualities.

Note: All event handlers registered via on() must return a Promise.

/**
 * @name 测试音乐源
 * @description 我只是一个测试音乐源哦
 * @version 1.0.0
 * @author xxx
 * @homepage http://xxx
 */

const { EVENT_NAMES, request, on, send } = window.lx

// ... implementation ...

on(EVENT_NAMES.request, ({ source, action, info }) => {
  if (action === 'musicUrl') {
    return Promise.resolve(someUrl)
  }
})

send(EVENT_NAMES.inited, {
  status: true,
  openDevTools: false,
  sources: {
    kw: {
      name: '酷我音乐',
      type: 'music',
      actions: ['musicUrl'],
      qualitys: ['128k', '320k', 'flac'],
    },
  },
})

NetEase Cloud Music "My Favorites" (我喜欢) playlists require authentication. To open them in lx-music-desktop, you must append a MUSIC_U token to the playlist ID or URL using the format: [id|url]###token.

Example Formats:

• https://music.163.com/#/playlist?id=11332&userid=123456###xxxxxx
• 11332###xxxxxx

How to get your MUSIC_U token:

1. Log in to NetEase Cloud Music in a web browser.
2. Open Developer Tools (F12).
3. For Chrome/360/QQ Browsers:
   • Go to the Application tab.
   • Expand Cookies on the left and select https://music.163.com.
   • Find the entry with Name MUSIC_U and copy its Value.
4. For Firefox:
   • Go to the Storage tab.
   • Expand Cookies on the left and select https://music.163.com.
   • Find the entry with Name MUSIC_U and copy its Value.

Warning: Your token is a temporary identity credential. Do not share it with others.

When adding support for a new language in the lx-music-desktop project, the language folder name must strictly match the specific locale codes listed below. These codes follow the language-country format (e.g., en-us).

- `ar-sa` - Arabic Saudi Arabia
- `cs-cz` - Czech Czech Republic
- `da-dk` - Danish Denmark
- `de-de` - German Germany
- `el-gr` - Modern Greek Greece
- `en-au` - English Australia
- `en-gb` - English United Kingdom
- `en-ie` - English Ireland
- `en-us` - English United States
- `en-za` - English South Africa
- `es-es` - Spanish Spain
- `es-mx` - Spanish Mexico
- `fi-fi` - Finnish Finland
- `fr-ca` - French Canada
- `fr-fr` - French France
- `he-il` - Hebrew Israel
- `hi-in` - Hindi India
- `hu-hu` - Hungarian Hungary
- `id-id` - Indonesian Indonesia
- `it-it` - Italian Italy
- `ja-jp` - Japanese Japan
- `ko-kr` - Korean Republic of Korea
- `nl-be` - Dutch Belgium
- `nl-nl` - Dutch Netherlands
- `no-no` - Norwegian Norway
- `pl-pl` - Polish Poland
- `pt-br` - Portuguese Brazil
- `pt-pt` - Portuguese Portugal
- `ro-ro` - Romanian Romania
- `ru-ru` - Russian Russian Federation
- `sk-sk` - Slovak Slovakia
- `sv-se` - Swedish Sweden
- `th-th` - Thai Thailand
- `tr-tr` - Turkish Turkey
- `zh-cn` - Chinese China
- `zh-hk` - Chinese Hong Kong
- `zh-tw` - Chinese Taiwan