3个本地接口跑通 Nuclear：免费音乐流媒体播放器的控制与自动化实操手册

3个本地接口跑通 Nuclear免费音乐流媒体播放器的控制与自动化实操手册【免费下载链接】nuclearStreaming music player that finds free music for you项目地址: https://gitcode.com/GitHub_Trending/nu/nuclearNuclear 是一个开源免费、无广告无追踪的音乐流媒体播放器Tauri React 构建跑在 Windows/macOS/Linux内容全部由插件提供。对开发者来说它真正的价值是内置了 HTTP API、MCP 服务器和 MPD 服务器三个本地控制面——用 curl、bash 脚本或 AI Agent 就能完成搜索、入队、播放、状态监听这一整套操作本文全部给出可直接复制的命令和代码。为什么是它Nuclear 的架构决定了它的可控性。播放器本体只负责界面、播放引擎、队列、收藏和歌单所有内容能力——搜索、音频流、首页推荐、发现推荐、外部歌单导入——全部由插件注册的 provider 提供。你装几个源、用哪个源都在 Sources 视图里自由切换播放时由元数据 provider 提供曲目信息、流媒体 provider 负责找到实际音频流。这个模型意味着换数据源不用换播放器而所有 provider 的接口都走插件 SDK 定义的那套 API所以外部控制面能覆盖到播放器内部几乎所有功能。完整机制见 docs/core-concepts/how-nuclear-works.md。第二个差异点是控制协议的选择面。常见开源播放器如 mpd 本体走 MPD 协议很多带 Web 界面的播放器只给网页操作。Nuclear 同时内置三种HTTP REST SSE 事件流写脚本、做自建 remote、MCP 服务器让 Claude Code、Cursor 这类 AI 工具直接驱动播放器、MPD 兼容服务器mpc、ncmpcpp、mpDris2、桌面 bar 的 MPD 模块全部直接可用。三者互不冲突按需开启。环境搭建与首次调用这一节目标是让播放器跑起来并确认第一个本地控制接口可用。Linux 从源码跑需要 Rust 和 Node 22git clone https://gitcode.com/GitHub_Trending/nu/nuclear cd nuclear pnpm install pnpm dev前置依赖是 Node.js 22、pnpm 9、stable 版 Rust外加 Tauri 要求的平台依赖。跑起来后浏览器/桌面窗口打开播放器界面首次使用是空库去内置插件商店装一两个音乐源插件安装界面见下图装完后才能搜索和播放。验证工具链是否健康pnpm test # 跑全部 vitest 测试 pnpm type-check # TypeScript 检查Windows / macOS 用预构建版本直接下载对应平台的安装包Windows 用.exe免管理员权限的按用户安装或.msimacOS 用.dmg分 Apple Silicon 和 Intel 两个。macOS 首次打开会被 Gatekeeper 拦截处理方式见下文「高频问题速查」。启用 HTTP API 并验证打开 Settings → Integrations开启 Nuclear Jam页面会显示 API 基础地址形如http://192.168.1.42:4120/api。然后APIhttp://127.0.0.1:4120/api # 换成设置页显示的实际地址 curl -s $API/health # 预期输出: {status:ok} curl -s $API/playback # 预期: {status:paused,seek:0,duration:0} 之类看到{status:ok}就说明控制面已就绪后面所有 curl 和脚本都基于这个地址。核心能力拆解HTTP API 搜索入队与播放控制最常用的路径搜索 → 入队 → 播放三个 POST 请求完成。所有 action 端点成功时返回200 OK且无响应体失败返回带error字段的 JSON。APIhttp://127.0.0.1:4120/api # 搜索结果含 tracks / artists / albums / playlists 数组 curl -s -X POST $API/search -H Content-Type: application/json \ -d {query:Daft Punk,types:[tracks],limit:10} # 把第一首加入队列tracks 里取完整 track 对象 curl -s -X POST $API/queue/add -H Content-Type: application/json \ -d {tracks:[$(curl -s -X POST $API/search -H Content-Type: application/json \ -d {query:Daft Punk,types:[tracks],limit:1} | head -c 999999 | grep -o tracks:\[.*\] | sed s/tracks://)]} curl -s -X POST $API/playback/play # 开始播放 curl -s -X POST $API/playback/next # 切下一首 curl -s -X POST $API/playback/seek -H Content-Type: application/json -d {seconds:30}完整端点表还有/api/queue查队列、/api/queue/remove删歌、/api/settings/{id}读写单个设置项见 docs/integrations/http-api.md。MCP 服务器让 AI Agent 驱动播放器想让 Claude Code、Cursor 这类工具直接控制播放器的话开 MCP 服务器再用 Streamable HTTP 传输连http://127.0.0.1:8800/mcp。用 curl 走一遍完整握手能看到会话 ID 和工具调用返回BASEhttp://127.0.0.1:8800/mcp # 1. 初始化响应头里带 mcp-session-id curl -si -X POST $BASE -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:initialize,params:{ protocolVersion:2025-03-26, clientInfo:{name:curl-demo,version:0.0.1}, capabilities:{}}} | grep -i mcp-session-id # 2. 带上 session-id 调用工具列出 Queue 域的方法 SID上一步拿到的 session-id curl -s -X POST $BASE -H mcp-session-id: $SID \ -H Content-Type: application/json -H Accept: application/json, text/event-stream \ -d {jsonrpc:2.0,id:2,method:tools/call, params:{name:list_methods,arguments:{domain:Queue}}} 工具调用返回的是 JSON-RPC 结果包含该域的方法名和简短描述和你打开 MCP Inspector 里看到的一致。MCP 只有四个工具但覆盖全部功能设计成「先发现、后调用」的分层模式list_methods列某域的方法域包括 Queue、Playback、Metadata、Favorites、Playlists、Dashboard、Providers→method_details拿单个方法的参数名、类型、返回类型格式为Domain.method如Queue.addToQueue→describe_type拿Track、QueueItem、Playlist等复杂类型的 JSON 结构→call真正执行。每步返回的 payload 都很小AI 的 token 消耗可控。接入 Claude Code 一行命令claude mcp add nuclear --transport http http://127.0.0.1:8800/mcpMPD 服务器复用现成客户端Nuclear 内置 MPD 兼容服务器127.0.0.1:6600被占用时自动顺延到 6609开完即可被mpc、ncmpcpp、mpDris2 等客户端直接控制export MPD_HOST127.0.0.1 MPD_PORT6600 mpc status # 播放状态、音量、队列长度、当前曲进度 mpc currentsong # 当前曲目 title / artist / album mpc next mpc seek 10 # 相对跳转 10 秒协议支持 10 / -5 这种相对值它支持播放控制、队列管理、音量和idle通知但不支持曲库浏览和存储歌单。idle是关键能力客户端阻塞等待player播放状态/切歌、playlist队列变化、mixer音量、options循环随机四类子系统的变化这正是 ncmpcpp 实时刷新和 bar 面板 MPD 模块不轮询的原因。支持的命令全集见 docs/integrations/mpd-server.md。性能与稳定性处理用 SSE 事件推送替代状态轮询写监控脚本时最容易犯的错是每 2 秒 GET 一次/api/playback。/api/events是标准 SSE 流服务端在状态变化时主动推完整状态长连接一条顶掉所有轮询请求curl -N http://127.0.0.1:4120/api/events切歌时会持续收到event: queue完整队列 currentIndex、event: playbackstatus/seek/duration、event: settings三类事件data 都是对应域的完整 JSON 状态。改成「连接一次 事件驱动」之后请求量从每分钟 30 次降到接近 0。MCP 会话解析与断线重试MCP 用 Streamable HTTP初始化响应的 header 携带mcp-session-id后续所有工具调用必须带这个 header。解析时注意curl -si输出里 header 和 body 混在一起只 grep 响应头段。脚本形式init$(curl -si -X POST $BASE -H Content-Type: application/json -d init.json) SID$(echo $init | sed -n 1,/^\r$/p | grep -i ^mcp-session-id: | awk {print $2} | tr -d \r) [ -n $SID ] || { echo no session id, is the MCP server enabled?; exit 1; }局域网 remote 场景的断线重连用dev:remote把 Vite 绑到 0.0.0.0在局域网另一台设备上用 remote control 界面或脚本连 Nuclear 时WiFi 切换、休眠唤醒都会断流。bash 侧用循环包裹 SSE 连接即可自愈while true; do curl -sN ${API}/api/events # curl exit 18 连接中断短暂等待后自动重连 sleep 2 done效果是断网恢复后 2 秒内重新挂上事件流不用手动重启脚本。高频问题速查macOS 提示应用已损坏打不开现象双击 Nuclear 弹出Nuclear.app is damaged and should be moved to the trash。原因发行版没有 Apple Developer 签名Gatekeeper 一律按损坏处理。解决sudo xattr -r -d com.apple.quarantine /Applications/Nuclear.app只需执行一次之后正常双击打开。Flatpak 版部分功能异常现象Flatpak 安装的版本里插件联网或音频流相关功能时好时坏。原因Flatpak 沙箱限制网络与文件系统访问Nuclear 的 Flatpak manifest 虽申请了必要权限但沙箱仍可能拦截部分行为。解决换用非沙箱格式。Debian 系用.debRPM 系用.rpm或通用.AppImageArch 用 AUR 的nuclear-player-bin预构建或nuclear-player-git源码。MCP 连接 8800 端口拒绝现象curl: (7) Failed to connect to 127.0.0.1 port 8800。原因8800 被其他进程占用Nuclear 自动顺延绑到了 8801–8809 中的某个端口。解决以 Settings → Integrations 里「MCP Server URL」字段显示的地址为准所有客户端配置claude mcp add、.cursor/mcp.json等统一改成实际地址或查占用后释放默认端口ss -ltnp | grep 8800 # 看谁占了端口完整工作流示例下面这个脚本把搜索、入队、播放、SSE 监听串成一个闭环适合做桌面歌词面板或状态 widget 的后端#!/usr/bin/env bash # Nuclear remote control: search - queue - play, then follow the song # SSE is the event source of truth; no polling against /api/playback APIhttp://127.0.0.1:4120/api queryDaft Punk - Get Lucky track$(curl -s -X POST $API/search -H Content-Type: application/json \ -d {\query\:\$query\,\types\:[\tracks\],\limit\:1}) # keep the whole track object: /api/queue/add expects Track[], not an id curl -s -X POST $API/queue/add -H Content-Type: application/json \ -d {tracks:$(echo $track | grep -o tracks:\[.*\] | sed s/tracks://)} /dev/null curl -s -X POST $API/playback/play /dev/null # reconnect on drop: exit 18 means the SSE stream broke while true; do curl -sN $API/events | while read -r line; do case $line in event:*playback*) prev$line ;; event:queue*) # queue event marks the actual song switch; playback events # also fire on seek, so use the queue event as the trigger [ $prev event:playback ] echo song changed: prev ;; data:*queue*) echo now at index $(echo $line | grep -o currentIndex:[0-9]*) ;; data:*playback*) echo $(echo $line | grep -o status:[a-z]*) ;; esac done sleep 2 done运行效果终端开始打印event: playback/data: {status:playing,...}手动或快捷键切歌时立刻多出一行 queue 事件和新的 currentIndex全程零轮询。搜索返回的数据结构、SSE 事件的完整字段见 docs/integrations/http-api.md。延伸方向与项目资源写一个自己的插件用nuclearplayer/plugin-sdk起步最小骨架就是onLoad/onEnable生命周期 api.Events、api.Queue等域 APITS 源码会被 esbuild 直接编译打包成一个 CommonJS 文件即可在 Nuclear 里加载。第一步跑通 plugins/getting-started.md 的最小示例插件。MPD 桌面集成用idleplayer/playlist子系统给 polybar/waybar 写一个 MPD 模块显示当前曲目。第一步mpc idle观察事件格式。yt-dlp 流媒体扩展通过 Ytdlp API 让插件解析视频站点作为音频源文档在 plugins/ytdlp.md。第一步先手动确认目标站点 yt-dlp 能出流。自建 remote 面板基于 SSE 事件流写一个浏览器页面只消费/api/events 少量 POST action就是一个完整 remote。第一步用本文的 bash 事件监听改成EventSource。有价值的资源路径用户手册packages/docs/user-manual/核心概念插件/provider/队列/历史记录packages/docs/core-concepts/三种集成HTTP API / MCP / MPDpackages/docs/integrations/插件开发全套文档packages/docs/plugins/插件 SDK 与 MCP 元数据实现packages/plugin-sdk/主题开发基础 CSS 主题 高级主题生成器packages/themes/贡献说明上游不收 PR扩展走插件CONTRIBUTING.md【免费下载链接】nuclearStreaming music player that finds free music for you项目地址: https://gitcode.com/GitHub_Trending/nu/nuclear创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考