Roon Controller

# Roon Control Skill

通过中文命令支持控制 Roon 音乐播放器。

## 快速开始

### 安装依赖

```bash pip install roonapi ```

### 使用示例

```python 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 Core - Token 自动保存到 `~/clawd/roon_config.json` - 重启后自动重连，无需重新授权

### 2. 区域选择和切换 - 支持切换任何可用区域 - 选定的区域保存在配置中，并在重启后保留 - 如果未选择区域，默认为以 "[roon]" 结尾的区域 - 使用 `set_zone()` 通过编程方式切换区域

**切换区域** ```python result = controller.set_zone("Living Room") # {"success": True, "message": "Switched to zone: Living Room", "zone": "Living Room"} ```

**获取当前区域** ```python zone = controller.get_current_zone() # Returns zone info dict with zone_id and zone_data ```

### 3. 播放控制

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

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

**播放/暂停切换** ```python result = controller.play_pause() ```

**上一曲** ```python result = controller.previous() ```

**下一曲** ```python result = controller.next() ```

### 4. 获取当前曲目

```python 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. 列出所有区域

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

## 命令行工具

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

```bash # 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 ```

## 中文命令支持

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

| 命令 | 含义 | 示例 | |---------|---------|---------| | 音乐播放 / 播放音乐 | 开始播放 | "音乐播放" | | 暂停 / 暂停播放 | 暂停播放 | "暂停一下" | | 下一曲 / 切歌 | 下一首 | "下一曲" | | 上一曲 | 上一首 | "上一曲" | | 当前曲目 / 正在放什么 | 查看当前曲目 | "当前曲目" |

## 错误处理

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

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

### 常见错误

- **Muspi zone not found**：检查 Roon 区域名称是否以 "muspi" 结尾 - **Failed to connect to Roon**：确保 Roon Core 正在运行且可从网络访问 - **Token load failed**：首次运行需要授权，确保授权顺利完成

## 注意事项

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

## 技术详情

### 依赖项 - `roonapi>=0.1.6`：官方 Roon API Python 库

### Token 管理 - Token 存储路径：`~/clawd/roon_config.json` - 自动加载：每次启动时自动加载 - 自动保存：首次授权或更新时自动保存

### 区域查找算法 ```python # 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] ```