星澜音乐插件开发文档

本文档说明星澜音乐 JS 插件的当前协议。插件用于扩展音源搜索、首页推荐、在线播放解析、歌词获取、音效/音质档位和插件自定义设置。

1. 插件文件

导入文件支持 .js 和 .mjs。
本地导入时，应用会把脚本复制到私有目录：files/plugins/<pluginId>/index.js。
内置插件放在：app/src/main/assets/plugins/<pluginId>/index.js。
本地导入插件如果需要设置页面，推荐把 HTML 写在 JS 字符串里；内置插件可以使用单独 HTML 文件。

2. 基础结构

插件必须把对象挂到 globalThis.AstralTidePlugin：

var plugin = {
  id: "com.example.demo",
  name: "示例插件",
  version: "1.0.0",
  description: "演示星澜音乐插件协议",
  supports: {
    homeInfo: true,
    searchInfo: true,
    songPlayback: true,
    songLyrics: true,
    soundEffect: true
  }
};

globalThis.AstralTidePlugin = plugin;

字段说明：

id：插件声明 ID，建议使用反向域名。
name：插件名称。
version：插件版本。
description：插件简介。
supports：能力声明。旧插件也可以只实现对应函数，应用会兼容识别。

3. 插件设置页

每个插件卡片都会显示“设置”按钮。插件声明了设置页时按钮可点击；没有声明时按钮为灰色不可点击。

本地导入插件推荐使用内联 HTML：

var plugin = {
  id: "com.example.lyrics",
  name: "歌词示例",
  version: "1.0.0",
  description: "演示插件设置页",

  settings: {
    html: `
<!doctype html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <style>
    body { margin: 0; padding: 20px; font-family: sans-serif; color: #111; }
    label { display: flex; justify-content: space-between; margin: 16px 0; }
  </style>
</head>
<body>
  <h2>歌词显示</h2>
  <label>显示翻译 <input id="translation" type="checkbox"></label>
  <label>显示罗马音 <input id="romanization" type="checkbox"></label>

  <script>
    const bridge = window.AstralTidePluginConfig;
    const config = JSON.parse(bridge.getConfig() || "{}");
    config.lyrics = config.lyrics || {};

    const translation = document.getElementById("translation");
    const romanization = document.getElementById("romanization");

    translation.checked = config.lyrics.showTranslation !== false;
    romanization.checked = config.lyrics.showRomanization !== false;

    function save() {
      config.lyrics.showTranslation = translation.checked;
      config.lyrics.showRomanization = romanization.checked;
      bridge.setConfig(JSON.stringify(config));
    }

    translation.addEventListener("change", save);
    romanization.addEventListener("change", save);
  </script>
</body>
</html>`
  }
};

globalThis.AstralTidePlugin = plugin;

内置插件也可以使用文件路径：

settings: {
  page: "settings.html"
}

路径相对于插件目录，例如 app/src/main/assets/plugins/demo/settings.html。

4. 配置 JSON

设置页通过 window.AstralTidePluginConfig 读写配置：

getConfig() / readConfig()：返回当前 JSON 字符串，默认 {}。
setConfig(json) / writeConfig(json) / saveConfig(json)：写入 JSON 对象字符串。
toast(message)：显示一条应用内提示。

配置文件保存到：

text

files/plugins/<pluginId>/config.json

歌词显示配置建议使用：

json

{
  "lyrics": {
    "showTranslation": true,
    "showRomanization": true
  }
}

showTranslation 和 showRomanization 分开控制。应用展示歌词时会按该配置过滤翻译和罗马音。

5. 歌词协议

插件通过 getSongLyrics(song, context) 或旧写法 getLyrics(song, context) 提供歌词。

var plugin = {
  name: "歌词插件",
  supports: { songLyrics: true },

  getSongLyrics(song, context) {
    const config = context.config || {};
    const lyricsConfig = config.lyrics || {};

    return {
      format: "LRC",
      lyricText: song.originalLyricText || song.lyricText || "",
      translatedLyricText: lyricsConfig.showTranslation === false ? "" : "[00:01.00]翻译",
      romanizedLyricText: lyricsConfig.showRomanization === false ? "" : "[00:01.00]romaji",
      karaokeLyricText: ""
    };
  }
};

song 会带入以下常用字段：

歌曲信息：platform、id、songId、name、artist、album、durationMs、cover、playUrl。
原歌词：lyricText、primaryText、originalLyricText、lyrics。
翻译：translatedLyricText、translatedText、translationText。
罗马音：romanizedLyricText、romanizedText、romanizationText、romajiText。
逐字歌词：karaokeLyricText。

返回对象必须标明歌词格式：

推荐字段：format。
兼容字段：lyricFormat、lyricsFormat、formatName、type、lyricType。
只填写歌词格式，不填写来源平台。例如酷我逐字歌词返回 format: "LRCX"，不要返回 format: "酷我音乐"。
字符串返回和历史对象未写格式时，应用会按 LRC 或内容特征兜底识别；新插件不要依赖兜底推断。

支持的 format 值如下。表中的“来源/平台”仅用于辨认格式，不需要也不应该作为返回值：

格式	来源/平台	粒度
`QRC`	QQ音乐	逐字
`KRC`	酷狗音乐	逐字
`TRC`	天天动听	逐字
`LRCX`	酷我音乐	逐字
`KSC`	小灰熊字幕 / KBuilder	逐字
`ESLyric`	foobar2000 插件	逐字
`Enhanced LRC` / `A2 LRC`	社区扩展	逐字
`LRC`	通用标准	逐行
`SRT` / `SSA` / `ASS`	通用视频字幕	逐行
`SMI`	Windows Media	逐行

context 会带入：

platform: "android"。
pluginId。
config / pluginConfig：设置页保存的 JSON。
lyricsDisplay.showTranslation。
lyricsDisplay.showRomanization。

返回值支持：

字符串：兼容旧插件，会当作 LRC 主歌词。
对象：推荐字段为 format、lyricText、translatedLyricText、romanizedLyricText、karaokeLyricText。
兼容字段：originalLyricText、primaryText、translatedText、translationText、romanizedText、romajiText、lyrics、lyric、tlyric、romalrc、yrc。

播放器展示顺序固定为：

主歌词。
罗马音，字号小于主歌词、大于翻译。
翻译，字号最小。

6. 在线播放解析

插件通过 getSongPlayback(song, context) 返回播放信息：

getSongPlayback(song, context) {
  return {
    playUrl: "https://example.com/audio.mp3",
    lyricText: "[00:01.00]原歌词",
    translatedLyricText: "[00:01.00]翻译",
    romanizedLyricText: "[00:01.00]romaji"
  };
}

返回字符串时会被当作 playUrl。返回对象时必须至少包含 playUrl、url 或 streamUrl。播放解析中返回的歌词字段仅作为兜底歌词；需要返回非 LRC、逐字歌词或多语言歌词时，应实现 getSongLyrics(song, context) 并在返回对象中声明 format。

7. 搜索协议

声明搜索结果类型：

searchConfig: {
  defaultTypeKey: "songs",
  loadStrategy: "preload",
  types: [
    { key: "songs", name: "歌曲", category: "song", handler: "searchSongs" },
    { key: "playlists", name: "歌单", category: "playlist", handler: "searchPlaylists" }
  ]
}

搜索函数接收 { keyword, keywords, page, limit, typeKey }，返回数组或对象：

searchSongs(context) {
  return {
    songs: [
      {
        id: "123",
        name: "歌曲名",
        artist: "歌手",
        album: "专辑",
        cover: "https://example.com/cover.jpg",
        durationMs: 180000
      }
    ],
    hasMore: false
  };
}

category 支持：song、playlist、artist、user、lyric、mv。

8. 首页和歌单

首页数据函数：

getHomeData(context) {
  return {
    dailyRecommendations: [],
    randomSongs: [],
    hotPlaylists: []
  };
}

歌单详情和歌曲列表：

getPlaylistDetail(playlist) {
  return { id: playlist.id, name: "歌单", cover: "https://example.com/cover.jpg" };
}

getPlaylistTracks(playlist) {
  return { songs: [], hasMore: false };
}

9. HTTP 请求

插件运行时提供同步请求桥：

const json = AstralTide.getJson({
  url: "https://example.com/api",
  method: "GET",
  headers: { Accept: "application/json" }
});

可用方法：

AstralTide.request(options)：返回 { status, headers, body }。
AstralTide.getJson(options)：解析 JSON。
AstralTide.getText(options)：返回文本。

10. 音效和音质

音效/音质插件可以返回档位：

getAudioQualities() {
  return [
    {
      id: "surround360",
      name: "360°环绕",
      description: "增强空间感",
      badge: "Demo",
      effect: {
        enableEqualizer: true,
        bandLevels: [220, 120, 0, 180, 300],
        bassBoostStrength: 560,
        virtualizerStrength: 1000,
        stereoPan: { enabled: true, depth: 0.2, periodMs: 2200 }
      }
    }
  ];
}

可用字段：

bandLevels：五段均衡器电平。
bassBoostStrength：低音增强，通常 0-1000。
virtualizerStrength：虚拟环绕，通常 0-1000。
stereoPan：左右声道摆动配置。

11. 调试清单

确认脚本末尾设置了 globalThis.AstralTidePlugin。
确认导入文件是 .js 或 .mjs。
设置页按钮灰色时，检查是否声明了 settings.html、settingsHtml 或 settings.page。
设置页保存失败时，检查传给 setConfig() 的内容是否是 JSON 对象字符串。
歌词不显示翻译或罗马音时，检查 config.json 中的 lyrics.showTranslation 和 lyrics.showRomanization。

星澜音乐插件开发文档 ​

1. 插件文件 ​

2. 基础结构 ​

3. 插件设置页 ​

4. 配置 JSON ​

5. 歌词协议 ​

6. 在线播放解析 ​

7. 搜索协议 ​

8. 首页和歌单 ​

9. HTTP 请求 ​

10. 音效和音质 ​

11. 调试清单 ​