音源机制详解——洛雪音乐为什么能跨平台搜歌

什么是自定义源

自定义源（Custom Source）是洛雪音乐的核心架构设计。它是一个用 JavaScript 编写的脚本文件（通常 .js 后缀），通过洛雪音乐在宿主环境中注入的 API，来完成以下事情：

• 搜索歌曲：接收关键词，返回匹配的歌曲列表。
• 获取播放 URL：根据歌曲信息和指定音质，返回可播放的音频地址。
• 获取歌词：返回 LRC 格式的歌词（以及可选的翻译歌词、罗马音歌词、逐字歌词）。
• 获取专辑封面：返回封面图片的 URL。
• 获取歌单：返回指定平台的歌单列表和歌单内的歌曲。

软件本身不实现任何以上功能——它只是加载脚本、注入 API、接收脚本返回的数据并渲染。

架构图（文字版）

┌─────────────────────────────────────────────┐
│            洛雪音乐宿主进程                    │
│  ┌─────────┐   ┌───────────────┐   ┌──────┐ │
│  │ 搜索界面 │   │  播放控制     │   │ 歌词 │ │
│  └────┬────┘   └──────┬────────┘   └──┬───┘ │
│       │               │               │     │
│       ▼               ▼               ▼     │
│  ┌───────────────────────────────────────┐  │
│  │  音源调度器（自动换源 / 回退机制）      │  │
│  └───────────────────┬───────────────────┘  │
│                      ▼                       │
│  ┌───────────────────────────────────────┐  │
│  │  脚本沙箱 ─── 注入 API（lx.request）   │  │
│  └───────────────────┬───────────────────┘  │
└──────────────────────┼──────────────────────┘
                       ▼
              ┌─────────────────────┐
              │  .js 自定义源脚本     │
              │  （搜索 / 取 URL     │
              │    / 取歌词 / 取封面）│
              └─────────┬───────────┘
                        ▼
              ┌─────────────────────┐
              │  第三方音乐平台接口    │
              │  （脚本内部实现具体请求）│
              └─────────────────────┘

宿主进程把请求分发给音源脚本，脚本负责发起实际的网络请求并返回数据。如果某个源失败，调度器自动换下一个源。

脚本的基本结构

每个音源脚本文件开头需要声明元信息：

/**
 * @name 音源显示名称
 * @description 音源简介
 * @version 1.0.0
 * @author 作者
 * @homepage http://example.com
 */

脚本通过 const { EVENT_NAMES, request, on, send } = globalThis.lx; 获取宿主注入的 API，然后：

1. 在脚本加载完成后，向宿主发送 inited 事件，声明自己支持哪些音质和操作。
2. 通过 on() 注册事件处理函数，响应宿主发起的搜索、取 URL、取歌词等请求。
3. 使用 request() 发起跨域不受限的 HTTP 请求，从第三方平台获取数据。

支持的音质

音源脚本可以声明支持以下音质等级：

不同平台的音源脚本可能支持不同的音质，具体以导入后音源脚本的声明为准。在播放或下载时，你可以在设置中指定默认音质。

换源与回退机制

洛雪音乐支持多音源并行。当你导入了多个音源脚本后：

1. 搜索时，所有已启用的音源会同时或依次请求，结果合并后展示。
2. 播放时，软件优先使用默认音源的 URL。如果获取失败，自动尝试下一个音源——这就是「换源」。
3. 如果所有已启用的音源都失败，会提示「换源失败，请尝试手动切换」。

换源机制不是让你手动一个个试，而是软件自动完成的调度过程。导入多个音源脚本是防止「换源失败」的最佳策略。

脚本生命周期

• 导入：.js 文件通过导入对话框加载到宿主。
• 初始化：脚本发送 inited 事件，声明自己的能力。
• 运行：宿主按事件驱动模式与脚本交互。
• 失效：第三方平台接口变化或脚本作者停止维护，脚本可能开始返回空结果或报错。
• 移除：在自定义源管理界面删除该脚本的记录，或直接覆盖为新的脚本文件。

安全提示

音源脚本是第三方代码，运行在沙箱环境中但仍需谨慎：

• 只从可信渠道获取音源脚本。
• 不要运行内容不明的 .js 文件。
• 音源脚本只需要 HTTP 请求能力，不需要文件系统或系统调用权限。

相关阅读

• 如何导入第一个音源 —— 具体操作步骤。
• 初始化失败与排错 —— 导入后没成功怎么办。
• 自定义源脚本编写指南 —— 如果你想自己写音源。