roon-controller

# Roon Control Skill Control the Roon music player with Chinese command support. ## Quick Start ### Install Dependencies ```bash pip install roonapi ``` ### Usage Examples ```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']}") ``` ## Core Features ### 1. Automatic Discovery and Connection - Automatic Roon Core discovery - Token automatically saved to `~/clawd/roon_config.json` - Auto-reconnect after restart, no re-authorization needed ### 2. Zone Selection and Switching - Supports switching between any available zone - Selected zone is saved in config and persists across restarts - If no zone is selected, defaults to zones ending with "[roon]" - Use `set_zone()` to switch zones programmatically **Switch Zone** ```python result = controller.set_zone("Living Room") # {"success": True, "message": "Switched to zone: Living Room", "zone": "Living Room"} ``` **Get Current Zone** ```python zone = controller.get_current_zone() # Returns zone info dict with zone_id and zone_data ``` ### 3. Playback Control **Play** ```python result = controller.play() # {"success": True, "message": "Playback started", "zone": "Living Room Muspi"} ``` **Pause** ```python result = controller.pause() # {"success": True, "message": "Paused", "zone": "Living Room Muspi"} ``` **Play/Pause Toggle** ```python result = controller.play_pause() ``` **Previous Track** ```python result = controller.previous() ``` **Next Track** ```python result = controller.next() ``` ### 4. Get Current Track ```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. List All Zones ```python zones = controller.list_zones() # ["Living Room Muspi", "Kitchen", "Bedroom"] ``` ## Command Line Tool The script can be used as a command line tool: ```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 ``` ## 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: ```python { "success": True/False, "message": "Operation result description", "zone": "Zone name (optional)" } ``` ### Common Errors - **Muspi zone not found**: Check if the Roon zone name ends with "muspi" - **Failed to connect to Roon**: Ensure Roon Core is running and network-accessible - **Token load failed**: First run requires authorization, ensure authorization completes successfully ## 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 - `roonapi>=0.1.6`: Official Roon API Python library ### Token Management - Token storage path: `~/clawd/roon_config.json` - Auto-load: Automatically loaded on each startup - Auto-save: Automatically saved on first authorization or update ### Zone Finding Algorithm ```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] ```