MusicArk
返回官网 下载 OpenAPI

OPENAPI 3.1 · REST · BEARER

把 MusicArk，
接进你的应用。

从账号连接、曲库发现到直放、转码、静音感知衔接、封面、歌词和个人状态同步，一套契约完成第三方播放器的完整接入。

开始接入 下载机器契约

快速开始

一次认证，后续只发送 Token

播放器用 MusicArk 用户名和密码建立连接。验证成功后，服务端返回随机的 mak_… Bearer Token；密码不再随曲库、图片或媒体请求发送。

01 · 建立播放器连接
curl -sS -X POST \
  'http://设备IP:13038/api/core/v1/player/session' \
  -H 'Content-Type: application/json' \
  --data '{
    "username": "alice",
    "password": "your-password",
    "client_name": "客厅播放器",
    "device_id": "living-room-player-01"
  }'
02 · 携带 Bearer Token
BASE_URL='http://设备IP:13038/api/core/v1'
PLAYER_TOKEN='mak_...'

curl -sS "$BASE_URL/catalog/tracks?limit=50" \
  -H "Authorization: Bearer $PLAYER_TOKEN"
设备身份

每个客户端安装应生成并持久保存独立的 device_id。同一账号和设备再次登录会轮换密钥并立即使旧密钥失效，不会累积多个有效令牌。

最小权限

按能力授权，不共享账户边界

普通用户连接默认获得四项播放器权限。管理员可以额外获得或显式签发 library:write；普通用户即使取得同名 Scope 也不能执行管理员维护操作。

catalog:read

浏览曲库

曲目、专辑、艺术家、文件夹、共享统计、搜索、首页、推荐、封面、歌词和个人列表读取。

playback:stream

读取音频

查询转码 Profile，创建可选静音感知的 ListeningSession，读取直放、渐进转码或 HLS。

playback:control

管理播放状态

维护个人播放策略、无缝播放偏好、共享队列、收藏和歌单。

playback:report

同步设备进度

按设备读取和上报进度，并通过稳定 playback_id 保证播放统计幂等。

library:write

管理员曲库维护

编辑标签与封面、写回文件、整理、扫描和受保护的文件操作。

完整播放链路

发现、播放、同步，保持同一条资源路径

客户端必须使用服务端返回的不透明资源 ID、分页游标、媒体 URL 与实际 MIME。不能从名称推导 ID，也不能把长期 Token 放进 URL。

01

发现、统计与搜索

GET /catalog/tracksGET /catalog/statisticsGET /catalog/query?q=

列表使用 limit 和 after 游标分页；统计可用 refresh=true 强制重算。

02

读取内容

GET /catalog/tracks/{id}GET /images/{id}?size=512

封面和歌词同样要求 Bearer Token，并支持 ETag 缓存。

03

协商播放能力

GET /preferences/me/transcodingPOST /listening-sessions

个人开关开启时提交 apply_silence_skip，按响应决定直放、转码或 HLS。

04

读取、Seek 与衔接

GET /listening-sessions/{id}/stream

使用 audible_start_ms 起播、在 audible_end_ms 切换；转码 Seek 创建新会话。

05

上报与恢复

POST /player/progressGET /player/progress

建议播放中每 10–15 秒上报，并在暂停、切歌和完成时补报。

06

同步个人数据

GET/PUT /me/playback-queueGET/POST /playlists

收藏、歌单、队列和设备进度始终绑定 Token 所属用户。

无缝播放由客户端完成

gapless_playback 同时是服务端账户许可：只有它与会话的 apply_silence_skip 都为 true 才会使用静音边界，账户关闭时客户端不能绕过。播放器仍需按顺序、随机、列表循环或单曲循环预载下一首，并防止时间回调与 ended 重复切歌。没有有效静音分析时会话返回完整范围且不会即时运行 FFmpeg。全局静音分析设置与任务只接受管理员 CookieSession，播放器 Bearer 不能管理。

开发者资源

契约、实例文档与接入验证

静态契约适合预先生成类型；客户端上线前还应使用目标 MusicArk 实例提供的同镜像契约进行校验。

OPENAPI 3.1

下载完整机器契约

包含路径、请求结构、响应 Schema、权限要求与稳定错误模型。

下载 openapi.yaml RUNNING INSTANCE

打开本机实例文档

默认端口为 13038；远程设备请把 127.0.0.1 替换为 MusicArk 所在设备 IP。

/api-docs LIVE CONTRACT

读取实例实际契约

用于客户端生成、兼容性比较和部署后的最终验收。

/openapi.yaml

ERROR MODEL

根据状态码与稳定 code 分支

所有 API 错误使用 application/problem+json。客户端不应根据本地化的标题或详情判断逻辑。

{
  "status": 403,
  "code": "API_TOKEN_SCOPE_REQUIRED",
  "detail": "当前接口需要 catalog:read 权限。",
  "request_id": "req_01..."
}

安全清单

Token 是设备凭证，不是分享链接

远程连接应通过可信 HTTPS 入口；密码只用于建立连接，Token 只存入系统安全存储。