名称： roon-controller
描述： 通过 Roon API 控制 Roon 音乐播放器，支持自动发现 Core 和区域筛选。提供播放/暂停、上一曲/下一曲、当前曲目查询等功能。自动识别 Muspi 区域，支持中文语音指令。

Roon 控制技能

通过中文指令控制 Roon 音乐播放器。

快速开始

安装依赖

pip install roonapi

使用示例

from roon_controller import RoonController

# 创建控制器（令牌会自动保存）
controller = RoonController(verbose=True)

# 播放/暂停
result = controller.play_pause()

# 下一曲
result = controller.next()

# 获取当前曲目
track_info = controller.get_current_track()
print(f"正在播放：{track_info['track']}")

核心功能

1. 自动发现与连接

• 自动发现 Roon Core
• 令牌自动保存至 ~/clawd/roon_config.json
• 重启后自动重连，无需重新授权

2. 区域选择与切换

• 支持在任意可用区域间切换
• 选中的区域会保存在配置中，重启后依然有效
• 若未选择区域，默认使用名称以 "[roon]" 结尾的区域
• 可通过 set_zone() 以编程方式切换区域

切换区域

result = controller.set_zone("客厅")
# {"success": True, "message": "已切换至区域：客厅", "zone": "客厅"}

获取当前区域

zone = controller.get_current_zone()
# 返回包含 zone_id 和 zone_data 的区域信息字典

3. 播放控制

播放

result = controller.play()
# {"success": True, "message": "开始播放", "zone": "客厅 Muspi"}

暂停

result = controller.pause()
# {"success": True, "message": "已暂停", "zone": "客厅 Muspi"}

播放/暂停切换

result = controller.play_pause()

上一曲

result = controller.previous()

下一曲

result = controller.next()

4. 获取当前曲目

track_info = controller.get_current_track()
# 返回：
# {
#   "success": True,
#   "is_playing": True,
#   "zone": "客厅 Muspi",
#   "track": "Bohemian Rhapsody",
#   "artist": "Queen",
#   "album": "A Night at the Opera",
#   "seek_position": 12345,  # 毫秒
#   "length": 354000        # 毫秒
# }

5. 列出所有区域

zones = controller.list_zones()
# ["客厅 Muspi", "厨房", "卧室"]

命令行工具

本脚本也可作为命令行工具使用：

# 播放
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 区域名称

中文指令支持

本技能支持以下中文触发词：

错误处理

所有方法均返回统一的字典结构：

{
    "success": True/False,
    "message": "操作结果描述",
    "zone": "区域名称（可选）"
}

常见错误

• 未找到 Muspi 区域：请检查 Roon 区域名称是否以 "muspi" 结尾
• 连接 Roon 失败：请确保 Roon Core 正在运行且网络可达
• 令牌加载失败：首次运行需要授权，请确保授权流程顺利完成

注意事项

1. 首次运行：需要在 Roon 中授权扩展，请留意 Roon 界面中的扩展授权提示
2. 区域命名：Muspi 区域名称必须以 "muspi" 结尾（不区分大小写）
3. 令牌存储：令牌保存在 ~/clawd/roon_config.json，请确保文件权限安全
4. 网络要求：运行脚本的设备必须与 Roon Core 在同一网络

技术细节

依赖项

• roonapi>=0.1.6：官方 Roon API Python 库

令牌管理

• 令牌存储路径：~/clawd/roon_config.json
• 自动加载：每次启动时自动加载
• 自动保存：首次授权或更新时自动保存

区域查找算法

# 查找所有区域
zones = roon.zones

# 筛选带有 muspi 后缀的区域
muspi_zones = [
    (zone_id, zone_data)
    for zone_id, zone_data in zones.items()
    if zone_data['display_name'].lower().endswith('muspi')
]

# 使用第一个匹配的区域
zone_id, zone_data = muspi_zones[0]