Roon控制技能

支持中文指令控制Roon音乐播放器

快速开始

安装依赖

pip install roonapi

使用示例

from roon_controller import RoonController

# Create controller (token will be saved automatically)
controller = RoonController(verbose=True)

# Play/Pause
result = controller.play_pause()

# Next track
result = controller.next()

# Get current track
track_info = controller.get_current_track()
print(f"Now playing: {track_info['track']}")

核心功能

1. 自动发现与连接

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

2. 区域选择与切换

• 支持在所有可用区域间切换
• 选定的区域将保存在配置中，重启后持续生效
• 若未选择区域，默认使用以"[roon]"结尾的区域
• 使用set_zone()通过编程方式切换区域

切换区域

result = controller.set_zone("Living Room")
# {"success": True, "message": "Switched to zone: Living Room", "zone": "Living Room"}

获取当前区域

zone = controller.get_current_zone()
# Returns zone info dict with zone_id and zone_data

3. 播放控制

播放

result = controller.play()
# {"success": True, "message": "Playback started", "zone": "Living Room Muspi"}

暂停

result = controller.pause()
# {"success": True, "message": "Paused", "zone": "Living Room Muspi"}

播放/暂停切换

result = controller.play_pause()

上一曲

result = controller.previous()

下一曲

result = controller.next()

4. 获取当前曲目

track_info = controller.get_current_track()
# Returns:
# {
#   "success": True,
#   "is_playing": True,
#   "zone": "Living Room Muspi",
#   "track": "Bohemian Rhapsody",
#   "artist": "Queen",
#   "album": "A Night at the Opera",
#   "seek_position": 12345,  # milliseconds
#   "length": 354000        # milliseconds
# }

5. 列出所有区域

zones = controller.list_zones()
# ["Living Room Muspi", "Kitchen", "Bedroom"]

命令行工具

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

# Play
python roon_controller.py play

# Pause
python roon_controller.py pause

# Previous track
python roon_controller.py prev

# Next track
python roon_controller.py next

# View current track
python roon_controller.py status

# List all zones
python roon_controller.py zones -v

# switch zone
python roon_controller.py switch zonename

中文命令支持

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

错误处理

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

{
    "success": True/False,
    "message": "Operation result description",
    "zone": "Zone name (optional)"
}

常见错误

• 未找到 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
• 自动加载：每次启动时自动加载
• 自动保存：首次授权或更新时自动保存

区域查找算法

# Find all zones
zones = roon.zones

# Filter zones with muspi suffix
muspi_zones = [
    (zone_id, zone_data)
    for zone_id, zone_data in zones.items()
    if zone_data['display_name'].lower().endswith('muspi')
]

# Use the first matching zone
zone_id, zone_data = muspi_zones[0]