LXMusic 中文文档 下载 App

自定义源脚本编写入门——自己写一个音源脚本

为什么要自己写音源脚本

洛雪音乐的自定义源接口文档是公开的，有 JavaScript 基础就能上手。

脚本的基本结构

每个音源脚本文件（.js）开头必须有元信息注释块：

/**
 * @name 音源显示名称
 * @description 音源简介
 * @version 1.0.0
 * @author 你的名字
 * @homepage http://your-site.com
 */

然后导入宿主注入的 API：

const { EVENT_NAMES, request, on, send } = globalThis.lx;

脚本核心逻辑包括三部分：

  1. 声明能力：加载完成后发送 inited 事件，告诉宿主你支持哪些音质、哪些操作。
  2. 事件处理：用 on() 注册宿主请求的处理函数。
  3. 发起请求：用 request() 从第三方平台获取数据。

宿主注入的核心 API

request(url, options, callback)

发起 HTTP 请求。与浏览器的 fetch 类似，但不受同源策略限制（脚本可以向任意域名发请求）。

request('https://api.example.com/search?q=' + keyword, (err, resp) => {
  if (err) return console.error(err);
  const data = JSON.parse(resp.body);
  // 处理数据
});

on(eventName, handler)

注册事件处理函数。宿主会向脚本发送各种请求事件：

on(EVENT_NAMES.request, ({ action, info, source }) => {
  if (action === 'musicUrl') {
    // info 包含歌曲信息和请求的音质
    const url = 'https://api.example.com/music/' + info.songmid + '/url';
    request(url, (err, resp) => {
      if (err) return send(EVENT_NAMES.response, { action, info, source, err });
      send(EVENT_NAMES.response, { action, info, source, data: resp.body });
    });
  }
});

send(eventName, data)

向宿主发送事件。最常用的是发送响应数据：

send(EVENT_NAMES.response, {
  action: 'musicUrl',
  source: 'my-source',
  info: { songmid: 'xxx' },
  data: 'https://audio.example.com/song.flac'
});

音质声明

脚本加载完成后，向宿主发送 inited 事件，声明自己支持哪些音质：

const qualitys = {
  mysource: {
    '128k': 'standard',
    '320k': 'high',
    'flac': 'lossless',
  }
};

send(EVENT_NAMES.inited, {
  source: 'mysource',
  name: '我的音源',
  qualitys
});

qualitys 对象映射了宿主请求的音质标识（左侧）到你的平台内部使用的音质参数（右侧）。

脚本编码要求

最简音源脚本骨架

/**
 * @name 测试音源
 * @description 我写的第一个音源脚本
 * @version 1.0.0
 * @author 我
 */

const { EVENT_NAMES, request, on, send } = globalThis.lx;

const sourceName = 'test-source';

// 1. 声明初始化
send(EVENT_NAMES.inited, {
  source: sourceName,
  name: '测试音源',
  qualitys: {
    testsource: { '128k': '1' }
  }
});

// 2. 注册请求处理
on(EVENT_NAMES.request, ({ action, info }) => {
  if (action === 'musicUrl') {
    // 获取播放 URL
    const url = 'https://your-api.com/music?id=' + info.songmid;
    request(url, (err, resp) => {
      if (err) return send(EVENT_NAMES.response, { action, info, source: sourceName, err });
      send(EVENT_NAMES.response, { action, info, source: sourceName, data: resp.body });
    });
  }
});

测试和调试

脚本写好后：

  1. 打开洛雪音乐 → 设置 → 自定义源管理 → 导入。
  2. 选择你的 .js 文件。
  3. 勾选启用，看是否显示「初始化成功」。
  4. 按 Ctrl + Shift + I 打开开发者工具 → Console 标签，查看脚本输出的日志和错误。

开发者工具的 Console 是调试音源脚本的主要手段——console.log / console.error 的输出都会显示在那里。

学习资源

法律与合规

⚠️ 自行编写音源脚本时必须注意：

相关阅读