Roon Control Skill
Control the Roon music player with Chinese command support.
Quick Start
Install Dependencies
CODEBLOCK0
Usage Examples
CODEBLOCK1
Core Features
1. Automatic Discovery and Connection
- - Automatic Roon Core discovery
- Token automatically saved to INLINECODE0
- Auto-reconnect after restart, no re-authorization needed
2. Zone Selection and Switching
- - Supports switching between any available zone
- Selected zone is saved in config and persists across restarts
- If no zone is selected, defaults to zones ending with "[roon]"
- Use
set_zone() to switch zones programmatically
Switch Zone
CODEBLOCK2
Get Current Zone
CODEBLOCK3
3. Playback Control
Play
CODEBLOCK4
Pause
CODEBLOCK5
Play/Pause Toggle
CODEBLOCK6
Previous Track
CODEBLOCK7
Next Track
CODEBLOCK8
4. Get Current Track
CODEBLOCK9
5. List All Zones
CODEBLOCK10
Command Line Tool
The script can be used as a command line tool:
CODEBLOCK11
Chinese Command Support
The skill supports the following Chinese trigger words:
| Command | Meaning | Example |
|---|
| 音乐播放 / 播放音乐 | Start playback | "音乐播放" |
| 暂停 / 暂停播放 |
Pause playback | "暂停一下" |
| 下一曲 / 切歌 | Next track | "下一曲" |
| 上一曲 | Previous track | "上一曲" |
| 当前曲目 / 正在放什么 | View current track | "当前曲目" |
Error Handling
All methods return a unified dictionary structure:
CODEBLOCK12
Common Errors
- - Muspi zone not found: Check if the Roon zone name ends with "muspi"
- Failed to connect to Roon: Ensure Roon Core is running and network-accessible
- Token load failed: First run requires authorization, ensure authorization completes successfully
Notes
- 1. First Run: Extension authorization required in Roon, check for the extension authorization prompt in Roon interface
- Zone Naming: Muspi zone names must end with "muspi" (case-insensitive)
- Token Storage: Token is saved in
~/clawd/roon_config.json, ensure secure file permissions - Network Requirements: The device running the script must be on the same network as Roon Core
Technical Details
Dependencies
- -
roonapi>=0.1.6: Official Roon API Python library
Token Management
- - Token storage path: INLINECODE4
- Auto-load: Automatically loaded on each startup
- Auto-save: Automatically saved on first authorization or update
Zone Finding Algorithm
CODEBLOCK13
Roon 控制技能
支持中文命令的Roon音乐播放器控制技能。
快速开始
安装依赖
bash
pip install roonapi
使用示例
python
from roon_controller import RoonController
创建控制器（令牌将自动保存）
controller = RoonController(verbose=True)
播放/暂停
result = controller.play_pause()
下一曲
result = controller.next()
获取当前曲目
track
info = controller.getcurrent_track()
print(f正在播放: {track_info[track]})
核心功能
1. 自动发现与连接
- - 自动发现Roon Core
- 令牌自动保存至 ~/clawd/roon_config.json
- 重启后自动重连，无需重新授权
2. 区域选择与切换
- - 支持切换任意可用区域
- 所选区域保存至配置，重启后持久化
- 未选择区域时，默认选择以[roon]结尾的区域
- 使用 set_zone() 方法编程切换区域
切换区域
python
result = controller.set_zone(Living Room)
{success: True, message: 已切换到区域: Living Room, zone: Living Room}
获取当前区域
python
zone = controller.getcurrentzone()
返回包含zoneid和zonedata的区域信息字典
3. 播放控制
播放
python
result = controller.play()
{success: True, message: 播放已开始, zone: Living Room Muspi}
暂停
python
result = controller.pause()
{success: True, message: 已暂停, zone: Living Room Muspi}
播放/暂停切换
python
result = controller.play_pause()
上一曲
python
result = controller.previous()
下一曲
python
result = controller.next()
4. 获取当前曲目
python
trackinfo = controller.getcurrent_track()
返回:
{
success: True,
is_playing: True,
zone: Living Room Muspi,
track: Bohemian Rhapsody,
artist: Queen,
album: A Night at the Opera,
seek_position: 12345, # 毫秒
length: 354000 # 毫秒
}
5. 列出所有区域
python
zones = controller.list_zones()
[Living Room Muspi, Kitchen, Bedroom]
命令行工具
该脚本可作为命令行工具使用：
bash
播放
python roon_controller.py play
暂停
python roon_controller.py pause
上一曲
python roon_controller.py prev
下一曲
python roon_controller.py next
查看当前曲目
python roon_controller.py status
列出所有区域
python roon_controller.py zones -v
切换区域
python roon_controller.py switch zonename
中文命令支持
该技能支持以下中文触发词：
| 命令 | 含义 | 示例 |
|---|
| 音乐播放 / 播放音乐 | 开始播放 | 音乐播放 |
| 暂停 / 暂停播放 |
暂停播放 | 暂停一下 |
| 下一曲 / 切歌 | 下一曲 | 下一曲 |
| 上一曲 | 上一曲 | 上一曲 |
| 当前曲目 / 正在放什么 | 查看当前曲目 | 当前曲目 |
错误处理
所有方法返回统一的字典结构：
python
{
success: True/False,
message: 操作结果描述,
zone: 区域名称（可选）
}
常见错误
- - 未找到Muspi区域：检查Roon区域名称是否以muspi结尾
- 连接Roon失败：确保Roon Core正在运行且网络可达
- 令牌加载失败：首次运行需要授权，确保授权完成
注意事项
- 1. 首次运行：需要在Roon中授权扩展，检查Roon界面中的扩展授权提示
- 区域命名：Muspi区域名称必须以muspi结尾（不区分大小写）
- 令牌存储：令牌保存在 ~/clawd/roon_config.json，确保文件权限安全
- 网络要求：运行脚本的设备必须与Roon Core在同一网络
技术细节
依赖项
- - roonapi>=0.1.6：Roon官方API Python库
令牌管理
- - 令牌存储路径：~/clawd/roon_config.json
- 自动加载：每次启动时自动加载
- 自动保存：首次授权或更新时自动保存
区域查找算法
python
查找所有区域
zones = roon.zones
过滤带有muspi后缀的区域
muspi_zones = [
(zone
id, zonedata)
for zone
id, zonedata in zones.items()
if zone
data[displayname].lower().endswith(muspi)
]
使用第一个匹配的区域
zone
id, zonedata = muspi_zones[0]
