bodian-music-api

独立的波点音乐 Node.js 客户端。提供请求签名、扫码登录、搜索、歌曲/歌单/专辑/歌手、Discover、音源与歌词、个人曲库、红心和自建歌单歌曲增删。

这是可直接加载的调用库，不启动 HTTP 服务。支持 Node.js 24+；Electron 只能在主进程使用。没有浏览器、Docker 服务、短信登录或歌单/专辑收藏写入实现。

安装与使用

npm install --save-exact [email protected]

const { randomBytes } = require('node:crypto');
const { createBodianApi } = require('bodian-music-api');

// Persist a generated device identifier in your host application and reuse it after restart.
const api = createBodianApi({ deviceId: randomBytes(16).toString('hex') });
const result = await api.request('search', { query: '示例', limit: 20, offset: 0 });
if (result.ok) console.log(result.data.resultList.length);
else console.error(result.error.code, result.error.message);

request() 只接受已登记的操作与简单参数，返回 { ok: true, data } 或 { ok: false, error: { code, message } }。未知操作和非法参数不会发出网络请求。BODIAN_OPERATIONS 和 index.d.cts 列出支持的操作和类型。传入的 uid、token 不替代实例会话。

会话与扫码

默认每个实例独立保存内存会话。宿主可以注入同步的 sessions：

• get() 返回 { uid, token, user: { id, nickname, avatarUrl } } 或 null。
• set(session) 与 clear() 必须每次递增只读 revision。
• 宿主负责安全持久化；不要在 renderer、浏览器存储或日志中存放 token。

调用 login_qr_key 获得 { key }，再调用 login_qr_create 传 { key } 得到 { imageUrl }。 间隔至少两秒调用 login_qr_check。状态为 waiting、scanned、confirmed 或 expired；认证成功后通过注入的会话存储保存凭据，结果只返回状态。 关闭登录界面时调用 login_qr_cancel。logout 清理本地会话与二维码状态；login_status 只返回本地恢复的用户信息，不声称进行了实时远端鉴权。 账号请求被平台拒绝时清除对应会话；迟到的旧请求不清除更新后的账号。

Electron 传输

const { net } = require('electron');
const api = createBodianApi({
  deviceId: persistedDeviceId,
  sessions: encryptedSessionStore,
  requestFactory(options, onResponse) {
    const request = net.request(options);
    request.on('response', onResponse);
    return request;
  },
});

在 Electron ready 后发送请求。requestFactory 是宿主集成入口，由可信主进程设置；不要允许 renderer 自定义它。 默认传输使用 Node https。保留播放接口要求的 GET JSON body；Electron 自行管理 Content-Length。支持 gzip 与 Chromium 已解压的响应，默认请求超时 15 秒、响应上限 8 MiB。 库不安装证书、不修改系统代理、不配置浏览器 CORS；Electron 的 IPC、safeStorage 与媒体策略由宿主负责。

数据与分页

目录结果保留波点原始字段，宿主负责转换成自己的歌曲、歌单和界面类型。分页返回 bodianPagination: { nextOffset, hasMore }；使用 nextOffset 继续请求，不要使用 list.length 推算偏移。请求 limit 范围为 1–100。歌曲可能缺失或重复，服务端 total 不保证等于可见歌曲数量。

Discover 使用 home_module（moduleId: 1）和 ai_playlist_detail（index），完整曲目在 musicList。 收藏歌单与专辑由同一个混合列表分流。user_albums 返回 albumList，user_playlists 的 collected.playLists 不含专辑。两者均保留过滤前的 bodianPagination，不返回混合列表的 total；即使当前分类页为空， 只要 hasMore=true，仍应按 nextOffset 继续读取。 audio 接受 id/quality/freeSign，音质为 standard/high/lossless/hires，Hi-Res 当前回退普通 FLAC。试听返回 preview 信息，调用方应避免将试听当作完整歌曲。 lyrics 返回 { mainText, wordByWordText }：前者是行歌词，后者是已解码 AWLRC 文本或 null，可交给宿主通用解析器。

播放仅限中国大陆网络使用。业务码 407 返回 region-restricted 错误并保留上游说明（缺失时使用地区限制提示）， 不会清除账号会话。宿主应提示网络地区限制并停止自动跳歌。

写入前库会通过当前会话读取并校验目标歌单，like_song 使用当前账号的系统红心歌单。不会提供任意 URL、接口路径或 renderer 凭据代理。

开发与发布

npm ci
npm run typecheck
npm test
npm pack --dry-run

测试使用本地模拟响应，不访问真实账号。CI 在 Windows、macOS、Linux 的 Node 24 上执行；通过 CI 不等于完成各平台真实账号或图形界面验收。 协议调查及已知限制见 docs/protocol.md。测试 helper 只供离线验收，不包含在发布包中。

维护者为 Mintcolour。版本按 SemVer 发布，调用方应固定已验证版本；平台协议变化在本仓库处理，Folia 集成通过依赖升级获得修复。源码及协议调查来源见 NOTICE，许可见 LICENSE。