Snapcast Stream Plugin 开发指南：基于 JSON-RPC 2.0 的播放控制与元数据插件协议

音视频【免费下载链接】snapcastSynchronous multiroom audio player项目地址https://gitcode.com/gh_mirrors/sn/snapcast点击查看免费下载本篇技术指南以 doc/json_rpc_api/stream_plugin.md 为骨架结合 Snapcast 服务器端源码server/streamreader/、server/control_requests.cpp与随安装包发布的示例插件server/etc/plug-ins/完整讲解 Stream Plugin 的协议定义、生命周期、全部请求/通知的 JSON 报文格式以及如何为 MPD、Mopidy、librespot 等音源编写可用的控制插件。读完本文你将掌握 Snapcast 服务器与插件之间通过 stdin/stdout 交换 NDJSON 的完整接口并能自行实现或调试一个 Stream Plugin。什么是 Stream PluginStream Plugin 是 Snapcast 服务器为某个音频流启动的一个可执行二进制或脚本它为流提供两类能力播放控制播放、暂停、停止、上一曲/下一曲、跳转seek等状态与元数据上报当前播放状态、音量、播放位置以及当前曲目的艺术家、专辑、封面等元数据。插件与 Snapcast 服务器的通信方式是通过 stdin/stdout 交换 NDJSONnewline delimited JSON 格式的 JSON-RPC-2.0 消息Snapcast 服务器向插件的stdin写入 JSON-RPC 2.0请求request插件向stdout输出响应response和通知notification插件的 stderr 输出会被服务器逐行读取并映射为服务器日志见下文ScriptStreamControl::stderrReadLine。协议本身遵循 JSON-RPC 2.0 规范。官方文档同时说明未来版本还可能支持共享库shared library形式的插件目前实现的是可执行脚本/二进制。一个流对应一个插件controlscript 参数插件通过流源stream source参数controlscript与某个流绑定。最典型的例子是 MPD 元数据插件[stream] source pipe:///tmp/snapfifo?nameMPDcontrolscriptmeta_mpd.py规则与细节相对路径解析如果controlscript是相对路径Snapserver 会在插件目录/usr/share/snapserver/plug-ins中查找脚本。该目录可通过配置项stream.plugin_dir修改默认值定义在 server/server_settings.hpp命令行参数--stream.plugin_dir在 server/snapserver.cpp 中注册。随服务器安装自带示例插件meta_mpd.pyMPD和meta_mopidy.pyMopidy此外仓库的 server/etc/plug-ins/ 目录下还有example.py、meta_go-librespot.py、plex_bridge.py等可参考的脚本。额外参数通过controlscriptparams传递参数必须URL 编码空格用%20例如--mopidy-host192.168.42.23%20--debug参见 doc/configuration.md。服务器总会附加的参数由 ScriptStreamControl::doStart 实现--stream流的 id总是传入当 HTTP 接口启用时额外传入--snapcast-porthttp.port和--snapcast-hosthttp.host。完整的流源 URI 语法doc/configuration.mdTYPE://host/path?namename[codeccodec][sampleformatsampleformat][chunk_mschunk ms][controlscriptcontrol script filename[controlscriptparamscontrol script command line arguments]]协议总览三类请求与三类通知一个 Stream Plugin必须支持并处理 Snapcast 服务器发送的以下三个请求requestsPlugin.Stream.Player.ControlPlugin.Stream.Player.SetPropertyPlugin.Stream.Player.GetProperties同时插件可以向服务器发送以下通知notificationsPlugin.Stream.Player.Properties属性变化通知Plugin.Stream.Log日志消息Plugin.Stream.Ready就绪通知应尽早发送。启动握手流程插件启动 → 尽快发送Plugin.Stream.Ready→ 服务器收到后立即发起Plugin.Stream.Player.GetProperties查询流的属性。这一流程在 PcmStream::onControlNotification 中实现收到Plugin.Stream.Ready通知后服务器立刻构造一次Plugin.Stream.Player.GetProperties请求发给插件。能力门控capability gating插件上报的布尔属性决定了服务器会发送哪些控制命令canGoNext/canGoPrevious是否支持next/previouscanPlay/canPause是否支持play/pause/playPausecanSeek是否支持seek/setPositioncanControl总开关。若为false服务器不会向插件发送任何控制命令。在服务器端这些门控由 PcmStream 的各个方法执行例如play()在!properties_.can_play时直接返回can_play_is_false错误pcm_stream.cppsetPosition()/seek()则检查can_seekpcm_stream.cpp。请求一Plugin.Stream.Player.Control用于控制播放器要求canControl为true。{id: 1, jsonrpc: 2.0, method: Plugin.Stream.Player.Control, params: {command: command, params: { param 1: value 1, param 2: value 2}}}支持的 commandcommand前置能力要求params说明playcanPlay无开始播放pausecanPause无暂停播放playPausecanPause无在播放/暂停之间切换stopcanControl无停止播放nextcanGoNext无跳转到下一曲previouscanGoPrevious无跳转到上一曲seekcanSeekoffsetfloat秒相对当前进度前/后跳转正数前进、负数后退setPositioncanSeekpositionfloat秒将播放位置设置为指定秒数示例{id: 1, jsonrpc: 2.0, method: Plugin.Stream.Player.Control, params: {command: setPosition, params: { position: 17.827 }}}预期响应成功{id: 1, jsonrpc: 2.0, result: ok}失败返回任意符合 JSON-RPC 2.0 错误对象 规范的错误错误消息应帮助用户诊断问题。在服务器端setPosition与seek的position/offset参数是必需的Stream.Control处理逻辑中缺少position或offset会抛出InvalidParamsExceptioncontrol_requests.cpp随后由PcmStream::sendRequest封装为对插件的Plugin.Stream.Player.Control请求pcm_stream.cpp。请求二Plugin.Stream.Player.SetProperty当canControl为true时Snapserver 会向插件发送SetProperty命令。{id: 1, jsonrpc: 2.0, method: Plugin.Stream.Player.SetProperty, params: {property: value}}支持的 propertyproperty类型说明loopStatusstring重复播放状态取值之一none播完列表后停止、track当前曲目播完后从头重播、playlist循环播放整个播放列表shufflebool是否随机顺序播放播放列表volumeint音量百分比合法范围[0..100]mutebool当前静音状态ratefloat当前播放速率合法范围(0..)预期响应成功{id: 1, jsonrpc: 2.0, result: ok}失败任意符合 JSON-RPC 2.0 规范的错误对象错误消息应帮助用户诊断。类型校验服务器端Stream.SetProperty对值做了严格校验control_requests.cpploopStatus必须是none/track/playlist之一shuffle、mute必须是 boolvolume必须是整数rate必须是 float否则抛出InvalidParamsException。Properties::fromJson中也将这些属性归类为可读写属性rw_props与只读属性ro_props未知属性会输出 Property not supported 警告properties.cpp。请求三Plugin.Stream.Player.GetProperties{id: 1, jsonrpc: 2.0, method: Plugin.Stream.Player.GetProperties}支持的 property响应 result 中返回除上述可写属性外还包括property类型说明playbackStatusstring当前播放状态playing/paused/stoppedloopStatusstring同 SetPropertynone/track/playlistshufflebool是否随机遍历播放列表volumeint音量百分比[0..100]mutebool当前静音状态ratefloat当前播放速率(0..)positionfloat当前播放位置秒canGoNextbool是否可以调用next并期望切曲canGoPreviousbool是否可以调用previous并期望切曲canPlaybool是否可用play/playPause开始播放canPausebool是否可用pause/playPause暂停canSeekbool是否可用seek/setPosition控制位置canControlbool是否允许通过该接口控制播放器metadatajson当前曲目元数据字段见下PlaybackStatus与LoopStatus在服务器端的字符串映射定义于 properties.hppplaying/paused/stopped、none/track/playlist之外的取值会被解析为kUnknown。metadata 支持的字段metadata是一个 JSON 对象全部字段均为可选语义对齐 MPRIS 规范基础信息trackIdstring曲目在 MPRIS 对象如 tracklist上下文中的唯一标识filestring当前歌曲文件durationfloat歌曲时长秒可含小数titlestring曲目标题namestring歌曲名称非标题。该标签含义不明确常被标签损坏的网络电台用来同时塞入歌手与歌名urlstring uri媒体文件位置artUrlstring uri代表曲目或专辑的图片地址。客户端不应假设播放器停止输出该 URL 后它仍存在artDatajsonBase64 编码的代表曲目/专辑的图片含两个子字段datastringBase64 编码的图像与extensionstring图片扩展名如 png、jpg、svg。若未指定artUrlSnapserver 会解码并缓存该图片并通过artUrl对外发布。艺术家与专辑artistlist of strings曲目艺术家artistSortlist of strings同artist但用于排序通常省略 The 等前缀albumstring专辑名albumSortstring同album用于排序albumArtistlist of strings专辑艺术家albumArtistSortlist of strings同albumArtist用于排序performerstring演唱/演奏者composerlist of strings作曲者conductorstring指挥lyrics/lyricistlist of strings歌词/作词者。日期与编号datestring发行日期通常为 4 位年份originalDatestring原始发行日期contentCreatedstring曲目创建时间通常年份有用firstUsedstring首次播放时间lastUsedstring最近播放时间discNumberinteger唱片编号trackNumberstring专辑/唱片中的曲目编号注意文档中该字段声明为 string示例实现中以 int 输出。分类与备注genrelist of strings曲目流派groupingstring声音属于更大类别时的分组名源自 IDv2.4.0 TIT1 描述workstring可表达为一个或多个音频录音的独立智力或艺术创作commentlist of strings自由格式备注labelstring厂牌或发行商名。评分与计数autoRatingfloat自动生成的评分依据播放频率等范围0.0..1.0userRatingfloat用户评分范围0.0..1.0useCountinteger曲目播放次数bpminteger每分钟节拍数。标识符MusicBrainz / SpotifymusicbrainzArtistId/musicbrainzAlbumId/musicbrainzAlbumArtistId/musicbrainzTrackId/musicbrainzReleaseTrackId/musicbrainzWorkIdstring对应 MusicBrainz 数据库中的各类 IDspotifyArtistId/spotifyTrackIdstringSpotify Artist / Track ID。服务器端Metadata类完整实现了上述字段的序列化/反序列化metadata.cpptoJson()输出全部标签fromJson()仅接受supported_tags集合内的键未知标签会记录警告artData仅在同时包含data与extension时才被解析。预期响应示例不带元数据的最小响应{id: 1, jsonrpc: 2.0, result: {canControl:true,canGoNext:true,canGoPrevious:true,canPause:true,canPlay:true,canSeek:false,loopStatus:none,playbackStatus:playing,position:93.394,shuffle:false,volume:86,mute:false}}带完整元数据的响应{id: 1, jsonrpc: 2.0, result: {canControl:true,canGoNext:true,canGoPrevious:true,canPause:true,canPlay:true,canSeek:true,loopStatus:none,metadata:{album:Doldinger,albumArtist:[Klaus Doldingers Passport],artUrl:http://coverartarchive.org/release/0d4ff56b-2a2b-43b5-bf99-063cac1599e5/16940576164-250.jpg,artist:[Klaus Doldingers Passport feat. Nils Landgren],contentCreated:2016,duration:305.2929992675781,genre:[Jazz],musicbrainzAlbumId:0d4ff56b-2a2b-43b5-bf99-063cac1599e5,title:Soul Town,trackId:7,trackNumber:6,url:Klaus Doldingers Passport - Doldinger (2016)/06 - Soul Town.mp3},playbackStatus:playing,position:72.79499816894531,shuffle:false,volume:97,mute:false}}通知一Plugin.Stream.Player.Properties格式与GetProperties的 result 相同{jsonrpc: 2.0, method: Plugin.Stream.Player.Properties, params: {canControl:true,canGoNext:true,canGoPrevious:true,canPause:true,canPlay:true,canSeek:false,loopStatus:none,playbackStatus:playing,position:593.394,shuffle:false,volume:86,mute:false}}增量更新语义如果params中缺少metadata服务器会沿用上一次已知的元数据。因此插件更新某个属性时不必重复发送完整的元数据。该逻辑在服务器端PcmStream::setProperties中实现新属性缺少metadata时用旧的properties_.metadata补齐pcm_stream.cpp。通知二Plugin.Stream.Log发送一条日志消息{jsonrpc: 2.0, method: Plugin.Stream.Log, params: {severity:Info,message:Log message}}支持的 severityseverity含义trace冗长的调试级消息debug调试级消息info信息性消息notice正常但值得注意的条件warning警告条件error错误条件fatal致命条件服务器收到该通知后会在日志中打印Plugin log - severity: severity, message: messagepcm_stream.cpp。此外插件 stderr 的每一行也会被服务器按关键字trace/debug/info/warning/error/fatal推断日志级别后写入日志PcmStream::onControlLog。通知三Plugin.Stream.Ready插件就绪、可以接收命令时发送此通知{jsonrpc: 2.0, method: Plugin.Stream.Ready}服务器收到后即查询流的属性发送Plugin.Stream.Player.GetProperties。参考实现中meta_mpd.py在完成 MPD 连接与初始状态同步后发送 Ready见 meta_mpd.pymeta_mopidy.py在 WebSocket 打开后发送 Readymeta_mopidy.py。服务器侧转发Stream.Control / Stream.SetProperty / Stream.OnPropertiesstream_plugin.md的 Server 一节注明该部分内容归属 doc/json_rpc_api/control.md原文标注TODO: this belongs to doc/json_rpc_api/control.md。外部客户端通过 Snapcast 的 JSON-RPC 接口控制流的报文格式如下Stream.Control等价于Plugin.Stream.Player.Control但 method 为Stream.Control且需携带流 id{id: 1, jsonrpc: 2.0, method: Stream.Control, params: {id: Pipe, command: command, params: params}}Stream.SetProperty等价于Plugin.Stream.Player.SetProperty{id: 1, jsonrpc: 2.0, method: Stream.SetProperty, params: {id: Pipe, property: property, value: value}}Stream.OnProperties服务器广播给客户端的属性通知等价于Plugin.Stream.Player.Properties但携带流 id{jsonrpc: 2.0, method: Stream.OnProperties, params: {id: Pipe, properties: {}}}服务器端Stream.Control/Stream.SetProperty的实现细节见 control_requests.cpp包括checkParams强制要求必需参数、setPosition/seek的秒→毫秒换算seconds * 1000、各属性的类型校验以及统一包装为result: ok的响应。安全限制通过 RPC 接口动态添加流时Stream.AddStreamstreamUri中的controlscript必须位于[stream] plugin_dir配置于snapserver.conf默认/usr/share/snapserver/plug-ins可以是绝对路径或相对路径control.md。服务器端通过utils::file::isInDirectory校验脚本必须位于插件目录内否则抛出InvalidParamsExceptioncontrol_requests.cpp。参考实现一example.py最小可运行插件example.py 是理解协议的最简入口核心结构如下参数解析用getopt解析--snapcast-host、--snapcast-port、--stream、-d/--debug、-v/--version默认值见defaults字典localhost、1780、default发送函数send()将 JSON 序列化后写到 stdout 并 flush末尾带换行NDJSON属性初始化exampleControl.__init__填充playbackStatusplaying、loopStatusnone、shuffleFalse、volume100、muteFalse、rate1.0、position0以及全部can*能力位updateProperties构造metadata含title、artist与artData——内置 Base64 的 Snapcast/Spotify SVG logoextensionsvg然后发送Plugin.Stream.Player.Properties通知主循环for line in sys.stdin: example_ctrl.control(line)——逐行读取服务器命令在control()中解析command示例仅处理next/previous更新属性后回{jsonrpc: 2.0, result: ok, id: id}日志通过Plugin.Stream.Log通知把收到的命令发回服务器日志severity: Info。该示例同时演示了artData的用法插件直接内嵌 Base64 图片数据服务器端 PcmStream::setProperties 会将其解码后存入ImageCache并自动生成artUrl形式的 HTTP 地址/__image_cache?namemd5对外发布。参考实现二meta_mpd.pyMPD 音源meta_mpd.py 是随安装包提供的生产级插件用于 MPD 流源依赖python-mpd2、musicbrainzngs、PyGObject、dbus-python。几个值得借鉴的设计状态映射status_mapping把 MPDstatus()的字段映射为 Snapcast 属性例如state→playbackStatusplay/pause/stop→playing/paused/stopped、repeat→loopStatus0/1/2→none/track/playlist、random→shuffle、volume、elapsed→position、duration、mutemeta_mpd.py标签映射tag_mapping把 MPD 的标签album、artist、musicbrainz_*等映射为 Snapcast metadata 字段含类型与是否为列表的声明meta_mpd.py能力位推导_get_properties中canSeek duration in snapstatus即只有当前曲目已知时长时才允许 seekmeta_mpd.py网络电台 hack当只有title、name、url而没有album/artist时把title按 - 或 / 拆分为 artist 与 titlemeta_mpd.py封面获取通过 MusicBrainz 查询专辑封面并缓存到_album_art_map仅在元数据不含artUrl时触发远程查询get_albumart命令处理control()按method的最后一个段分发——Control内的next/previous/play/pause/playPause/stop/setPosition/seek分别对应 MPD 命令其中seek用带符号的偏移字符串10/-10调用seekcursetPosition用绝对秒数SetProperty映射shuffle→random、loopStatus→repeat/single仅在 MPD 支持single命令时使用、volume→setvolGetProperties直接回传_get_properties(self.status())meta_mpd.py事件驱动基于 GLib 主循环支持 MPDidle命令仅在player/mixer/options/playlist子系统变化时强制刷新属性并发送通知_update_properties(forceTrue)。参考实现三meta_mopidy.py 与 meta_go-librespot.pymeta_mopidy.py通过 WebSocket依赖websocket-client 0.58.0连接 Mopidy 的 JSON-RPC 接口把 Snapcast 的 stdin 命令翻译为 Mopidy 的core.playback.*、core.tracklist.*、core.mixer.*调用。亮点包括send_batch_request批量查询一次拉取播放状态、重复/随机、音量、静音、时间位置等seek先取当前时间位置再加偏移后调用core.playback.seek在track_playback_started等事件通知时刷新属性loopStatus由 Mopidy 的repeatsingle两个标志组合推导repeat single→trackrepeat→playlist否则none。meta_go-librespot.py仓库 server/etc/plug-ins/ 中提供用于 go-librespot 流源配置示例见 doc/configuration.mdcontrolscriptmeta_go-librespot.pycontrolscriptparams--streamname%20--librespot-host127.0.0.1%20--librespot-port24879其中controlscriptparams需要 URL 编码。服务端实现纵深ScriptStreamControl 的进程与管道管理理解插件协议的服务端实现有助于调试插件行为StreamControl是基类定义了command()把请求投递到 asio strand 串行化并按请求 id 保存响应回调request_callbacks_与onReceive()用 jsonrpcpp 解析插件 stdout 的一行 JSON区分 notification / request / response 三种类型stream_control.cppScriptStreamControl用 Boost.Process 启动脚本stdout/stderr 各接一个管道用boost::asio::async_read_until(..., \n)逐行异步读取stdout 行进入onReceive()stderr 行进入日志回调stream_control.cpp命令下发doCommand()把 JSON-RPC 请求序列化后追加\n写入插件的 stdin 并 flushstream_control.cpp——这就是文档所述 newline delimited JSON-RPC-2.0 的服务端实现属性广播setProperties()在属性真正变化时通过pcmListeners_的onPropertiesChanged通知上层pcm_stream.cpp最终以Stream.OnProperties形式推送给连接的客户端。编写你自己的 Stream Plugin最小清单结合协议与示例实现编写一个插件需要满足逐行读取 stdin每行是一个 JSON-RPC 2.0 请求用请求中的id回包启动即发Plugin.Stream.Ready让服务器尽快发起GetProperties实现Plugin.Stream.Player.GetProperties至少返回canControl与相关can*能力位服务器据此决定是否下发控制命令实现Plugin.Stream.Player.Control/Plugin.Stream.Player.SetProperty若canControltrue成功回result: ok失败回符合规范的错误对象如{code: -32601, message: Method not found, id: ...}参考 example.py状态变化时发Plugin.Stream.Player.Properties通知元数据未变化时省略metadata字段即可处理 stderr 与Plugin.Stream.Log便于服务器侧排查问题处理命令行参数至少解析--streamid始终传入并在 HTTP 启用时解析--snapcast-port/--snapcast-host。从 server/etc/plug-ins/example.py 复制骨架是最快的起步方式。相关文档协议主文档doc/json_rpc_api/stream_plugin.md服务器 JSON-RPC 接口含 Stream.Control / Stream.SetProperty / Stream.OnProperties / Stream.AddStreamdoc/json_rpc_api/control.md流源 URI 与controlscript/controlscriptparams参数doc/configuration.md服务端插件控制实现server/streamreader/stream_control.hpp、server/streamreader/stream_control.cpp、server/streamreader/pcm_stream.cpp属性与元数据结构server/streamreader/properties.hpp、server/streamreader/properties.cpp、server/streamreader/metadata.cpp示例插件server/etc/plug-ins/example.py、server/etc/plug-ins/meta_mpd.py、server/etc/plug-ins/meta_mopidy.py、server/etc/plug-ins/meta_go-librespot.py赞分享音视频【免费下载链接】snapcastSynchronous multiroom audio player项目地址https://gitcode.com/gh_mirrors/sn/snapcast点击查看免费下载相关推荐基于 JSON-RPC 2.0 编写 DBX Go 原生 Sidecar 插件dbx-plugin-sdk 协议 v1 实战指南基于 JSON RPC 2.0 编写 DBX Go 原生 Sidecar 插件dbx plugin sdk 协议 v1 实战指南 DBX 原生 Sidecar数据库开发者工具桌面应用CLIMCP 服务AI 应用Transmission RPC 协议规范深度解析基于 JSON-RPC 2.0 的远程控制接口实战指南Transmission RPC 协议规范深度解析基于 JSON RPC 2.0 的远程控制接口实战指南 本文以 docs/rpc spec.md https桌面应用后端CLI网络nullclaw 外部渠道插件协议实战指南基于 stdio JSON-RPC 的 channels.external 插件开发与运维nullclaw 外部渠道插件协议实战指南基于 stdio JSON RPC 的 channels.external 插件开发与运维 nullclaw 通过人工智能AI Agent大模型自主智能体工具调用RAGAgent 记忆MCP ClientsAgent 沙箱多智能体语音上一篇DeepSeek-V3推理性能倍增MTP模块与Speculative Decoding实战优化指南下一篇从显存危机到效率革命DeepSeek-V3 FP8量化技术如何解锁超大规模模型训练创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考