sonos-music-playback

# Sonos 音乐点播 ## Overview 这个 skill 面向中文用户，用来沉淀可复用的 Sonos 点播工作流。 当前已验证兼容的音乐服务： - 网易云音乐 - QQ音乐 This skill assumes: - Sonos devices are reachable on the local network - the `sonos` CLI is installed and available in `PATH` - Sonos App has a working linked music-service authorization for the target service - service availability may vary by region and by the user's linked Sonos music services This skill avoids machine-specific hardcoded paths by resolving from: - `OPENCLAW_WORKSPACE_DIR` - `OPENCLAW_SONOS_VENV` - `OPENCLAW_SONOS_NETEASE_WRAPPER` - `OPENCLAW_SONOS_QQ_WRAPPER` - `OPENCLAW_SONOS_NETEASE_SCRIPT` - `OPENCLAW_SONOS_QQ_SCRIPT` Default behavior should remain simple: - workspace defaults to the current OpenClaw workspace inferred from the skill location - venv defaults to `$HOME/.openclaw/venvs/soco-sonos` - wrappers default to `./scripts/sonos_netease_play.sh` and `./scripts/sonos_qq_play.sh` under the workspace - playback scripts default to `./scripts/sonos_netease_play.py` and `./scripts/sonos_qq_play.py` under the workspace ## Quick Start Preferred simple install: ```bash ./skills/sonos-music-playback-market/scripts/install.sh ``` Manual flow if needed: ```bash ./skills/sonos-music-playback-market/scripts/check_env.sh ``` If the check fails, run bootstrap: ```bash ./skills/sonos-music-playback-market/scripts/bootstrap_env.sh ``` Then use the standard playback entrypoints, for example: ```bash ./scripts/sonos_netease_play.sh --room 'Living Room' '至少还有你' ./scripts/sonos_qq_play.sh --room 'Living Room' '稻香' ``` ## Workflow ### 1. Prefer one-command install Prefer `scripts/install.sh` when: - using the skill for the first time - after migration or system reinstall - handing the skill to another environment ### 2. Check environment Run `scripts/check_env.sh` when: - debugging a broken environment - validating an installation result ### 3. Bootstrap if needed Run `scripts/bootstrap_env.sh` when: - `soco` is missing - the Sonos Python venv does not exist - either playback wrapper is missing or not executable Bootstrap will: - create the Sonos Python venv if missing - install `soco` if missing - verify both playback wrappers and scripts exist Bootstrap does not install the `sonos` CLI. If `sonos` is missing, install or restore it separately. ### 4. Play through the standard wrappers Do not call the Python playback files with system `python3`. Prefer the wrappers because they pin the correct Python venv and avoid interpreter drift. ## Important implementation contract ### Preserve metadata by playing from queue When implementing or patching the playback logic, do not replace queue playback with a direct `play_uri(...)` rewrite. Correct pattern: - search via `sonos smapi search` - convert the selected result into a Sonos-accepted object with `SoCo MusicService(...)` - `add_to_queue(...)` - `play_from_queue(...)` This preserves Sonos App metadata such as: - title - artist - album - album art ### Do not trust search titles alone Search results through Sonos may contain: - same-title tracks by different artists - live / piano / cover / female / child / sentimental variants - results whose final queue metadata differs from the plain search title Prefer a two-stage selection strategy: 1. title-based initial filtering 2. queue-metadata-based rescoring using actual Sonos metadata ### QQ音乐-specific note `sonoscli` currently supports searching QQ音乐 via `sonos smapi search --service 'QQ音乐'`, but its `--open` flow still behaves like a Spotify-only path and does not directly play QQ search results. For QQ音乐, use the validated queue-based SoCo path instead of `sonos smapi search --open`. ## Troubleshooting ### Can search but cannot play First suspect linked service authorization state in Sonos App. A reliable recovery path is usually: - re-add or re-authorize the music service in Sonos App ### QQ音乐 auth page opens but does not complete in CLI This is likely an incompatibility in the current CLI auth/open flow rather than a proof that QQ音乐 itself is unavailable in Sonos. If Sonos App already has a working QQ音乐 binding and `sonos smapi search --service 'QQ音乐'` returns results, prefer the SoCo queue-based playback path. ### Plays but metadata is blank First inspect whether the playback path regressed to `play_uri(...)`. ### Still chooses the wrong version Inspect the actual queue metadata returned by Sonos. If the search source itself does not return the desired original version, this is a source-quality limitation, not necessarily a scoring bug. ## Release Checklist Before publishing or distributing this skill, verify: - `scripts/check_env.sh` returns `ready=yes` in a representative environment - `scripts/bootstrap_env.sh` can create the venv and install `soco` when missing - a real 网易云 playback command reaches `PLAYING` - a real QQ音乐 playback command reaches `PLAYING` - `nowPlaying.title` is non-empty after playback starts - the documented prerequisites match reality for the target environment ## Resources ### scripts/ - `scripts/install.sh` - one-command installer that runs bootstrap and validation, then prints example playback commands - `scripts/check_env.sh` - portable environment checker using environment-variable-based path resolution - `scripts/bootstrap_env.sh` - portable bootstrap script for the Sonos Python venv and `soco`, and verifies both playback entrypoints exist