Roon Controller

Roon Control Skill

Control the Roon music player with Chinese command support.

Quick Start

Install Dependencies

pip install roonapi

Usage Examples

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']}")

Core Features

1. Automatic Discovery and Connection

2. Zone Selection and Switching

Switch Zone

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

Get Current Zone

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

3. Playback Control

Play

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

Pause

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

Play/Pause Toggle

result = controller.play_pause()

Previous Track

result = controller.previous()

Next Track

result = controller.next()

4. Get Current Track

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. List All Zones

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

Command Line Tool

The script can be used as a command line tool:

# 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

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:

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

Common Errors

Notes

1. First Run: Extension authorization required in Roon, check for the extension authorization prompt in Roon interface 2. Zone Naming: Muspi zone names must end with "muspi" (case-insensitive) 3. Token Storage: Token is saved in ~/clawd/roon_config.json, ensure secure file permissions 4. Network Requirements: The device running the script must be on the same network as Roon Core

Technical Details

Dependencies

Token Management

Zone Finding Algorithm

# 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]

Install Dependencies

pip install roonapi

Usage Examples

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. First Run: Extension authorization required in Roon, check for the extension authorization prompt in Roon interface 2. Zone Naming: Muspi zone names must end with "muspi" (case-insensitive) 3. Token Storage: Token is saved in ~/clawd/roon_config.json, ensure secure file permissions 4. Network Requirements: The device running the script must be on the same network as Roon Core