Nuclear HTTP API 实战用本地 HTTP 接口驱动音乐播放、队列与搜索【免费下载链接】nuclearStreaming music player that finds free music for you项目地址: https://gitcode.com/GitHub_Trending/nu/nuclear本文基于 Nuclear 官方文档packages/docs/integrations/http-api.md展开完整覆盖其定义的状态查询、播放控制、队列操作、搜索与 SSE 事件流全部接口并结合packages/player/src-tauri/src/http_api/下的 Rust 实现逐条印证底层调用链。读完本文你可以直接用 curl、脚本或自研客户端接入 Nuclear 的本地 API实现远程播放控制、队列管理与实时状态同步。1. 启用 API 并获取访问地址HTTP API 不是独立服务而是挂在Nuclear JamNuclear 的局域网远程遥控功能之下启用 Nuclear Jam 后Nuclear 会在同时承载遥控 UI 的同一个服务器实例上暴露本地 HTTP API。启用步骤与官方文档一致打开Settings → Integrations开启Nuclear Jam面板中的API URL字段即为基地址形如http://192.168.1.42:4120/api。从源码可以确认几个文档未展开的运行细节服务监听在0.0.0.0所有网卡即局域网内其他设备可直接访问。mod.rs 中通过bind_first_available_port(0.0.0.0, ...)完成绑定端口并非固定 4120而是在4120–4129 的区间内逐个尝试取第一个可用端口REMOTE_PORT_START 4120、REMOTE_PORT_END 4129。这是 net.rs 中bind_first_available_port的行为因此实际端口以 Settings 里显示的 API URL 为准面板展示的局域网 IP 由local_lan_ip()计算它利用 RFC 5737 保留地址触发一次路由表查询而不产生真实网络请求。启动与停止由两个 Tauri 命令驱动http_api_start与http_api_stop见 mod.rs。其中http_api_start是幂等的——服务器已在运行时直接返回当前端口与局域网地址不会重复起服务停止时通过CancellationToken触发 axum 的优雅关闭。2. 状态查询接口State以下表为官方文档定义的完整状态接口后附源码中对应的桥接调用方法路径返回GET/api/health{ status: ok }GET/api/queue{ items: QueueItem[], currentIndex: number }GET/api/playback{ status: string, seek: number, duration: number }GET/api/settings{ shuffle: boolean, repeat: string, discovery: boolean, language: string, dark: boolean, themeId: string }GET/api/settings/{id}按完整限定 ID 返回单个设置项的值如core.playback.shuffle实现上routes.rs这些 GET 接口都是对前端插件桥的透传调用/api/queue→ 桥接方法Queue.getQueue/api/playback→ 桥接方法Playback.getState/api/settings并不是单一存储读取而是并发发起 6 次Settings.getGlobal调用tokio::try_join!聚合而成对应的完整限定 ID 分别是返回字段设置的完整限定 IDshufflecore.playback.shufflerepeatcore.playback.repeatdiscoverycore.playback.discoverylanguagecore.general.languagedarkcore.theme.darkthemeIdcore.theme.active.id/api/settings/{id}则把路径中的id原样传给Settings.getGlobal因此你可以查询任意完整限定 ID 的设置项而不限于上面 6 个聚合字段。/api/health是最简单的探活端点恒返回{ status: ok }适合脚本轮询服务是否可用。3. 播放与队列控制接口Actions所有 action 端点在成功时统一返回200 OK且无响应体。完整端点表如下方法路径请求体效果POST/api/playback/play无开始播放POST/api/playback/toggle无播放/暂停切换POST/api/playback/next无下一首POST/api/playback/previous无上一首POST/api/playback/seek{ seconds: number }跳转到指定位置POST/api/playback/shuffle{ enabled: boolean }开启或关闭随机播放POST/api/playback/repeat{ mode: off \| all \| one }设置循环模式POST/api/queue/add{ tracks: Track[] }向队列追加曲目POST/api/queue/remove{ ids: string[] }按 ID 移除队列项POST/api/search{ query: string, types?: SearchCategory[], limit?: number }搜索音乐见下文POST/api/settings/{id}任意 JSON 值按完整限定 ID 设置单个设置项actions.rs 揭示了每个端点到桥接方法的精确映射这对理解请求体直接透传至关重要HTTP 端点桥接方法请求体处理/api/playback/playPlayback.play无参数/api/playback/togglePlayback.toggle无参数/api/playback/nextQueue.goToNext无参数/api/playback/previousQueue.goToPrevious无参数/api/playback/seekPlayback.seekTo整个 JSON body 原样传入即{ seconds: n }/api/playback/shufflePlayback.setShuffleEnabledbody 原样传入即{ enabled: bool }/api/playback/repeatPlayback.setRepeatModebody 原样传入即{ mode: off\|all\|one }/api/queue/addQueue.addToQueuebody 原样传入即{ tracks: [...] }/api/queue/removeQueue.removeByIdsbody 原样传入即{ ids: [...] }值得注意的设计点seek、shuffle、repeat、queue 这几个端点不对 body 做 Rust 侧的结构校验而是作为serde_json::Value直接转发给前端插件层处理。这意味着参数格式错误的后果由前端桥接层以错误事件返回见第 6 节错误处理而不是在 axum 层返回 4xx。搜索端点的参数细节/api/search在 search.rs 中有明确的类型定义pub struct SearchParams { query: String, types: OptionVecSearchCategory, limit: Optionu32, } pub enum SearchCategory { Artists, Albums, Tracks, Playlists } // serde rename_all lowercase也就是说query为必填字符串types可选取值必须是小写字符串数组tracks、artists、albums、playlistslimit可选非负整数Rust 侧为u32。该端点最终调用桥接方法Metadata.search参数被包装为{ params: params }传递。成功时返回各字段均可能缺省{ tracks: Track[], artists: ArtistRef[], albums: AlbumRef[], playlists: PlaylistRef[] }4. 按 ID 读写单个设置项GET /api/settings/{id}与POST /api/settings/{id}构成对任意设置项的通用读写通道GET 把{id}传给Settings.getGlobal直接返回该设置的当前值JSON 标量或对象POST 接收任意 JSON 值作为 body包装为{ id: id, value: body }调用Settings.setGlobal成功返回200 OK无 body。例如把主题切到深色curl -X POST http://192.168.1.42:4120/api/settings/core.theme.dark \ -H Content-Type: application/json -d trueid必须是完整限定 IDcore.前缀的域路径这与第 2 节聚合设置使用的六个 ID 是同一套命名空间。5. 事件流GET /api/eventsSSEGET /api/events打开一条 Server-Sent Events 长连接。每当 Nuclear 内部状态变化服务器就会推送命名事件每个事件都携带其所属域的完整状态快照而非增量queue 事件event: queue data: {items:[...],currentIndex:3}playback 事件event: playback data: {status:playing,seek:42.1,duration:213.0}settings 事件event: settings data: {shuffle:false,repeat:off,discovery:false,language:en_US,dark:false,themeId:default}从 routes.rs 的events_stream实现可以看到三条补充事实连接建立时先收到一条connected注释行Event::default().comment(connected)客户端可据此确认握手成功流启用了keep-aliveKeepAlive::default()长连接期间会持续发送保活帧事件通道是容量为64的tokio::sync::broadcast通道见 mod.rs 中broadcast::channel(64)。若某个 SSE 客户端消费过慢导致落后通道会丢弃中间事件并记录SSE client lagged, skipped N events的警告日志——客户端不会收到任何已跳帧的通知但由于每个事件都是全量快照丢弃中间帧不影响最终状态收敛这正是全量快照设计的好处。事件的生产链路同样值得说明Rust 侧监听三类 Tauri 事件remote:queue、remote:playback、remote:settings由前端插件层发出经listen_for_event统一写入 broadcast 通道再分发给所有 SSE 订阅者。Nuclear 自己的遥控前端Nuclear Jam就消费这条 SSE 流。其 React hook useEventSource.ts 展示了稳健客户端的标准做法断线后以3 秒间隔重连最多重试 3 次超过后标记failed。如果你的脚本要长时间挂接/api/events建议采用相同的有限次重连 状态上报策略。6. 错误处理失败请求统一返回带error字段的 JSON 体{ error: Playback.toggle failed: no track in queue }状态码规则与官方文档一致500—— 桥接错误请求已到达 Nuclear 但命令执行失败。实现上 routes.rs 的BridgeErrorResponse将所有BridgeError含基础设施错误与处理器错误见 types.rs一律映射为500Json({ error: message })其他情况使用标准 HTTP 码。例如未匹配到任何 API 路由时请求落入前端静态资源回退frontend.rs 的serve_frontend找不到对应文件时返回 404。桥接层自身也有状态语义types.rs 中BridgeResponseBody是一个带status标签的枚举成功时携带data失败时携带error字符串——HTTP 层的 500 响应正是由该错误分支转换而来。7. 完整调用示例以下是一个最小的健康检查 → 状态轮询 → 控制播放脚本片段以文档中的示例地址为例BASEhttp://192.168.1.42:4120/api # 探活 curl -s $BASE/health # 查看队列与当前播放状态 curl -s $BASE/queue curl -s $BASE/playback # 播放 / 暂停 / 切歌 curl -s -X POST $BASE/playback/toggle curl -s -X POST $BASE/playback/next # 跳转到 90 秒 curl -s -X POST $BASE/playback/seek \ -H Content-Type: application/json -d {seconds: 90} # 关闭随机、设置整队循环 curl -s -X POST $BASE/playback/shuffle \ -H Content-Type: application/json -d {enabled: false} curl -s -X POST $BASE/playback/repeat \ -H Content-Type: application/json -d {mode: all} # 搜索限定 track 与 album各返回 10 条 curl -s -X POST $BASE/search \ -H Content-Type: application/json \ -d {query: jazz, types: [tracks, albums], limit: 10} # 实时事件流前台挂接CtrlC 退出 curl -s -N $BASE/events这些请求形式与仓库内遥控前端的集成测试完全一致测试文件 RemoteControl.test.tsx 逐项断言了/api/playback/toggle、/api/playback/next、/api/queue/remove、/api/search等端点的请求方法与 body 格式可作为官方客户端如何调用的参考实现。8. 适用前提与限制API 仅在Nuclear Jam 启用时运行且随应用生命周期启停http_api_start/http_api_stop端口在 4120–4129 内自动选择跨网络使用时应以 Settings 面板显示的 API URL 为准不要硬编码端口服务绑定在0.0.0.0任何同网段设备均可访问并控制播放无鉴权机制——在不安全的网络上使用时请注意暴露面action 端点的 body 直接透传给前端插件层参数合法性由桥接层校验并以 500 error字段反馈所有接口路径均以/api为前缀完整路由表定义在 routes.rs 的router函数中可作为端点的权威清单。官方文档原文见 http-api.md同目录下还有 mpd-server.md 与 mcp-server.md可与其他集成方式对照阅读。【免费下载链接】nuclearStreaming music player that finds free music for you项目地址: https://gitcode.com/GitHub_Trending/nu/nuclear创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Nuclear HTTP API 实战：用本地 HTTP 接口驱动音乐播放、队列与搜索
Nuclear HTTP API 实战用本地 HTTP 接口驱动音乐播放、队列与搜索【免费下载链接】nuclearStreaming music player that finds free music for you项目地址: https://gitcode.com/GitHub_Trending/nu/nuclear本文基于 Nuclear 官方文档packages/docs/integrations/http-api.md展开完整覆盖其定义的状态查询、播放控制、队列操作、搜索与 SSE 事件流全部接口并结合packages/player/src-tauri/src/http_api/下的 Rust 实现逐条印证底层调用链。读完本文你可以直接用 curl、脚本或自研客户端接入 Nuclear 的本地 API实现远程播放控制、队列管理与实时状态同步。1. 启用 API 并获取访问地址HTTP API 不是独立服务而是挂在Nuclear JamNuclear 的局域网远程遥控功能之下启用 Nuclear Jam 后Nuclear 会在同时承载遥控 UI 的同一个服务器实例上暴露本地 HTTP API。启用步骤与官方文档一致打开Settings → Integrations开启Nuclear Jam面板中的API URL字段即为基地址形如http://192.168.1.42:4120/api。从源码可以确认几个文档未展开的运行细节服务监听在0.0.0.0所有网卡即局域网内其他设备可直接访问。mod.rs 中通过bind_first_available_port(0.0.0.0, ...)完成绑定端口并非固定 4120而是在4120–4129 的区间内逐个尝试取第一个可用端口REMOTE_PORT_START 4120、REMOTE_PORT_END 4129。这是 net.rs 中bind_first_available_port的行为因此实际端口以 Settings 里显示的 API URL 为准面板展示的局域网 IP 由local_lan_ip()计算它利用 RFC 5737 保留地址触发一次路由表查询而不产生真实网络请求。启动与停止由两个 Tauri 命令驱动http_api_start与http_api_stop见 mod.rs。其中http_api_start是幂等的——服务器已在运行时直接返回当前端口与局域网地址不会重复起服务停止时通过CancellationToken触发 axum 的优雅关闭。2. 状态查询接口State以下表为官方文档定义的完整状态接口后附源码中对应的桥接调用方法路径返回GET/api/health{ status: ok }GET/api/queue{ items: QueueItem[], currentIndex: number }GET/api/playback{ status: string, seek: number, duration: number }GET/api/settings{ shuffle: boolean, repeat: string, discovery: boolean, language: string, dark: boolean, themeId: string }GET/api/settings/{id}按完整限定 ID 返回单个设置项的值如core.playback.shuffle实现上routes.rs这些 GET 接口都是对前端插件桥的透传调用/api/queue→ 桥接方法Queue.getQueue/api/playback→ 桥接方法Playback.getState/api/settings并不是单一存储读取而是并发发起 6 次Settings.getGlobal调用tokio::try_join!聚合而成对应的完整限定 ID 分别是返回字段设置的完整限定 IDshufflecore.playback.shufflerepeatcore.playback.repeatdiscoverycore.playback.discoverylanguagecore.general.languagedarkcore.theme.darkthemeIdcore.theme.active.id/api/settings/{id}则把路径中的id原样传给Settings.getGlobal因此你可以查询任意完整限定 ID 的设置项而不限于上面 6 个聚合字段。/api/health是最简单的探活端点恒返回{ status: ok }适合脚本轮询服务是否可用。3. 播放与队列控制接口Actions所有 action 端点在成功时统一返回200 OK且无响应体。完整端点表如下方法路径请求体效果POST/api/playback/play无开始播放POST/api/playback/toggle无播放/暂停切换POST/api/playback/next无下一首POST/api/playback/previous无上一首POST/api/playback/seek{ seconds: number }跳转到指定位置POST/api/playback/shuffle{ enabled: boolean }开启或关闭随机播放POST/api/playback/repeat{ mode: off \| all \| one }设置循环模式POST/api/queue/add{ tracks: Track[] }向队列追加曲目POST/api/queue/remove{ ids: string[] }按 ID 移除队列项POST/api/search{ query: string, types?: SearchCategory[], limit?: number }搜索音乐见下文POST/api/settings/{id}任意 JSON 值按完整限定 ID 设置单个设置项actions.rs 揭示了每个端点到桥接方法的精确映射这对理解请求体直接透传至关重要HTTP 端点桥接方法请求体处理/api/playback/playPlayback.play无参数/api/playback/togglePlayback.toggle无参数/api/playback/nextQueue.goToNext无参数/api/playback/previousQueue.goToPrevious无参数/api/playback/seekPlayback.seekTo整个 JSON body 原样传入即{ seconds: n }/api/playback/shufflePlayback.setShuffleEnabledbody 原样传入即{ enabled: bool }/api/playback/repeatPlayback.setRepeatModebody 原样传入即{ mode: off\|all\|one }/api/queue/addQueue.addToQueuebody 原样传入即{ tracks: [...] }/api/queue/removeQueue.removeByIdsbody 原样传入即{ ids: [...] }值得注意的设计点seek、shuffle、repeat、queue 这几个端点不对 body 做 Rust 侧的结构校验而是作为serde_json::Value直接转发给前端插件层处理。这意味着参数格式错误的后果由前端桥接层以错误事件返回见第 6 节错误处理而不是在 axum 层返回 4xx。搜索端点的参数细节/api/search在 search.rs 中有明确的类型定义pub struct SearchParams { query: String, types: OptionVecSearchCategory, limit: Optionu32, } pub enum SearchCategory { Artists, Albums, Tracks, Playlists } // serde rename_all lowercase也就是说query为必填字符串types可选取值必须是小写字符串数组tracks、artists、albums、playlistslimit可选非负整数Rust 侧为u32。该端点最终调用桥接方法Metadata.search参数被包装为{ params: params }传递。成功时返回各字段均可能缺省{ tracks: Track[], artists: ArtistRef[], albums: AlbumRef[], playlists: PlaylistRef[] }4. 按 ID 读写单个设置项GET /api/settings/{id}与POST /api/settings/{id}构成对任意设置项的通用读写通道GET 把{id}传给Settings.getGlobal直接返回该设置的当前值JSON 标量或对象POST 接收任意 JSON 值作为 body包装为{ id: id, value: body }调用Settings.setGlobal成功返回200 OK无 body。例如把主题切到深色curl -X POST http://192.168.1.42:4120/api/settings/core.theme.dark \ -H Content-Type: application/json -d trueid必须是完整限定 IDcore.前缀的域路径这与第 2 节聚合设置使用的六个 ID 是同一套命名空间。5. 事件流GET /api/eventsSSEGET /api/events打开一条 Server-Sent Events 长连接。每当 Nuclear 内部状态变化服务器就会推送命名事件每个事件都携带其所属域的完整状态快照而非增量queue 事件event: queue data: {items:[...],currentIndex:3}playback 事件event: playback data: {status:playing,seek:42.1,duration:213.0}settings 事件event: settings data: {shuffle:false,repeat:off,discovery:false,language:en_US,dark:false,themeId:default}从 routes.rs 的events_stream实现可以看到三条补充事实连接建立时先收到一条connected注释行Event::default().comment(connected)客户端可据此确认握手成功流启用了keep-aliveKeepAlive::default()长连接期间会持续发送保活帧事件通道是容量为64的tokio::sync::broadcast通道见 mod.rs 中broadcast::channel(64)。若某个 SSE 客户端消费过慢导致落后通道会丢弃中间事件并记录SSE client lagged, skipped N events的警告日志——客户端不会收到任何已跳帧的通知但由于每个事件都是全量快照丢弃中间帧不影响最终状态收敛这正是全量快照设计的好处。事件的生产链路同样值得说明Rust 侧监听三类 Tauri 事件remote:queue、remote:playback、remote:settings由前端插件层发出经listen_for_event统一写入 broadcast 通道再分发给所有 SSE 订阅者。Nuclear 自己的遥控前端Nuclear Jam就消费这条 SSE 流。其 React hook useEventSource.ts 展示了稳健客户端的标准做法断线后以3 秒间隔重连最多重试 3 次超过后标记failed。如果你的脚本要长时间挂接/api/events建议采用相同的有限次重连 状态上报策略。6. 错误处理失败请求统一返回带error字段的 JSON 体{ error: Playback.toggle failed: no track in queue }状态码规则与官方文档一致500—— 桥接错误请求已到达 Nuclear 但命令执行失败。实现上 routes.rs 的BridgeErrorResponse将所有BridgeError含基础设施错误与处理器错误见 types.rs一律映射为500Json({ error: message })其他情况使用标准 HTTP 码。例如未匹配到任何 API 路由时请求落入前端静态资源回退frontend.rs 的serve_frontend找不到对应文件时返回 404。桥接层自身也有状态语义types.rs 中BridgeResponseBody是一个带status标签的枚举成功时携带data失败时携带error字符串——HTTP 层的 500 响应正是由该错误分支转换而来。7. 完整调用示例以下是一个最小的健康检查 → 状态轮询 → 控制播放脚本片段以文档中的示例地址为例BASEhttp://192.168.1.42:4120/api # 探活 curl -s $BASE/health # 查看队列与当前播放状态 curl -s $BASE/queue curl -s $BASE/playback # 播放 / 暂停 / 切歌 curl -s -X POST $BASE/playback/toggle curl -s -X POST $BASE/playback/next # 跳转到 90 秒 curl -s -X POST $BASE/playback/seek \ -H Content-Type: application/json -d {seconds: 90} # 关闭随机、设置整队循环 curl -s -X POST $BASE/playback/shuffle \ -H Content-Type: application/json -d {enabled: false} curl -s -X POST $BASE/playback/repeat \ -H Content-Type: application/json -d {mode: all} # 搜索限定 track 与 album各返回 10 条 curl -s -X POST $BASE/search \ -H Content-Type: application/json \ -d {query: jazz, types: [tracks, albums], limit: 10} # 实时事件流前台挂接CtrlC 退出 curl -s -N $BASE/events这些请求形式与仓库内遥控前端的集成测试完全一致测试文件 RemoteControl.test.tsx 逐项断言了/api/playback/toggle、/api/playback/next、/api/queue/remove、/api/search等端点的请求方法与 body 格式可作为官方客户端如何调用的参考实现。8. 适用前提与限制API 仅在Nuclear Jam 启用时运行且随应用生命周期启停http_api_start/http_api_stop端口在 4120–4129 内自动选择跨网络使用时应以 Settings 面板显示的 API URL 为准不要硬编码端口服务绑定在0.0.0.0任何同网段设备均可访问并控制播放无鉴权机制——在不安全的网络上使用时请注意暴露面action 端点的 body 直接透传给前端插件层参数合法性由桥接层校验并以 500 error字段反馈所有接口路径均以/api为前缀完整路由表定义在 routes.rs 的router函数中可作为端点的权威清单。官方文档原文见 http-api.md同目录下还有 mpd-server.md 与 mcp-server.md可与其他集成方式对照阅读。【免费下载链接】nuclearStreaming music player that finds free music for you项目地址: https://gitcode.com/GitHub_Trending/nu/nuclear创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考