核心用法
Roon Controller是一款专为Roon音乐播放器设计的自动化控制工具，通过官方Python API实现与Roon Core的无缝对接。用户可通过Python代码或命令行直接操控音乐播放，无需打开Roon原生界面。
关键操作流程：
1. 首次运行自动发现网络中的Roon Core并完成授权
2. Token自动保存至~/clawd/roon_token.txt，后续免重复授权
3. 自动识别名称以"muspi"结尾的播放区域（不区分大小写）
4. 支持play()/pause()/next()/previous()/get_current_track()等核心操作
中文指令支持：内置"音乐播放"、"暂停"、"下一曲"、"上一曲"、"当前曲目"等触发词，降低中文用户使用门槛。
显著优点
- 零配置自动化：自动发现Core、自动保存Token、自动识别目标区域，用户仅需首次授权
- 双语交互：原生支持中英文命令，覆盖主流控制场景
- 标准化输出：统一返回
{success, message, zone}字典结构，便于脚本集成 - 命令行友好：可直接作为CLI工具使用，适合Home Assistant等自动化平台对接
潜在局限
1. 区域命名约束：强制要求目标区域名以"muspi"结尾，非标准命名需手动修改代码
2. 网络依赖严格：必须与Roon Core同网络运行，跨VLAN或Docker网络需额外配置
3. 功能边界明确：仅支持基础播放控制，不含音量调节、队列管理、搜索等进阶功能
4. 单区域操作：自动选择首个匹配区域，不支持多区域同时控制或区域切换
5. Token安全风险：明文存储Token文件，共享设备需注意文件权限
适合人群
- 已部署Roon生态且追求轻量控制的音频发烧友
- 需要将Roon集成至智能家居自动化工作流的用户
- 熟悉Python或命令行操作的技术型用户
常规风险
- 授权泄露：Token文件若被窃取，攻击者可远程控制播放（但无法访问音频文件本身）
- 误操作风险：中文自然语言指令可能被误触发，建议在封闭环境使用
- 网络中断：Core掉线后API调用将失败，需依赖调用方实现重试逻辑
- 版本兼容性：依赖
roonapi>=0.1.6，Roon Core重大更新可能导致API行为变更