fjgalesloot/roon-extension-mqtt

roon-extension-mqtt

镜像概述和主要用途

roon-extension-mqtt是一个Roon扩展，通过MQTT协议将Roon音乐系统集成到家庭自动化系统中。它能够订阅Roon区域更新并推送状态信息，同时支持通过MQTT消息发送控制命令，实现对Roon的远程管理和自动化控制。

核心功能和特性

• 状态监控：订阅所有Roon区域更新，推送基于node-roon-api-transport定义的Zone对象状态信息，主题格式为"roon/[区域名称]/..."
• 区域控制：支持通过MQTT发送播放、暂停、播放/暂停切换、停止、上一曲、下一曲等控制命令
• 设置管理：可配置区域的随机播放（shuffle）和重复播放（repeat）模式
• 音量控制：支持设置输出音量、静音及取消静音操作
• 播放位置调整：允许设置当前播放媒体的seek位置（秒）
• 电源管理：控制输出设备的电源状态（开启/待机）
• 内容浏览：支持浏览并播放互联网电台、播放列表、艺术家、专辑等内容，支持多种播放动作（立即播放、随机播放、加入队列等）

使用场景和适用范围

适用于希望通过家庭自动化系统（如Home Assistant、OpenHAB等）整合Roon音乐系统的用户，可实现：

• 远程控制Roon播放状态（如通过语音助手、手机应用）
• 基于家庭状态触发音乐播放自动化（如离家暂停、回家继续播放）
• 在智能设备上显示Roon播放状态信息
• 构建复杂的音乐控制场景（如定时播放、场景联动）

使用方法和配置说明

Docker部署

稳定版（master分支）

bash
docker run -v [卷或主机文件夹]:/usr/src/app/config/ docker.xuanyuan.run/fjgalesloot/roon-extension-mqtt:latest

开发版（beta分支）

bash
docker run -v [卷或主机文件夹]:/usr/src/app/config/ docker.xuanyuan.run/fjgalesloot/roon-extension-mqtt:beta

参数说明：

• -v [卷或主机文件夹]:/usr/src/app/config/：挂载配置目录，用于持久化扩展配置文件

MQTT主题结构说明

区域名称处理规则

• MQTT主题中不允许的字符（+、/、#）会被替换为"-"
• 区域分组名称中的"+ 1"等后缀会被忽略（如"Kitchen + 2"需使用"Kitchen"作为区域名称）

状态信息主题

扩展推送的区域状态信息基于node-roon-api-transport的Zone对象定义，主题格式为"roon/[区域名称]/..."。例如，名为"Zone1"的区域的单行播放信息主题为：

roon/Zone1/now_playing/one_line/line1

控制命令

通过向指定主题发布消息控制区域或输出：

设置管理

通过向指定主题发布消息修改区域设置：

音量控制

通过向指定主题发布消息调整输出音量：

roon/[区域名称]/outputs/[输出名称]/volume/set

支持的消息内容：

• 音量值（如65，设置具体音量）
• mute（静音）
• unmute（取消静音，设置音量时会自动取消静音）

注意：当前未对音量值进行有效性检查。

Seek位置调整

通过向指定主题发布消息设置当前播放媒体的位置（秒）：

roon/[区域名称]/seek/set

消息内容：秒数（如80表示设置播放位置为80秒）

注意：当前未对Seek位置进行有效性检查。

电源管理

通过向指定主题发布消息控制输出电源状态：

roon/[区域名称]/outputs/[输出名称]/power

支持的消息内容：

• on（开启电源）
• standby（进入待机状态）

内容浏览

支持浏览并播放多种内容，消息可使用标题字符串（不区分大小写）或JSON对象（用于更多控制）。内容层级参考https://roonlabs.github.io/node-roon-api/RoonApiBrowse.html#~loadresultcallback%E3%80%82

示例：

• 播放互联网电台：向roon/[区域名称]/browse/internet_radio发布消息"radio title"（电台标题）
• 播放播放列表（立即播放）：向roon/[区域名称]/browse/playlists发布消息"playlist title"（播放列表标题）
• 随机播放播放列表：向roon/[区域名称]/browse/playlists发布消息{"title":"playlist title", "action":"Shuffle"}
• 启动艺术家电台：向roon/[区域名称]/browse/artists发布消息{"title":"artist name", "action":"Start Radio"}
• 随机播放专辑：向roon/[区域名称]/browse/artists发布消息{"title":"artist name", "album":"album title", "action":"Shuffled"}
• 将专辑加入队列：向roon/[区域名称]/browse/artists发布消息{"title":"artist name", "album":"album title", "action":"Queue"}
• 播放专辑（立即播放）：向roon/[区域名称]/browse/albums发布消息"album title"（专辑标题，播放第一个匹配的专辑）