Sonos Netease Playback

Portable Sonos + Netease playback skill for OpenClaw environments. Use when an agent needs a standard reusable workflow to search and play a specific song to...

Security Scan

The skill's files and runtime instructions are coherent with its stated purpose (bootstrapping a Python venv, installing soco, and providing wrappers to play music via the sonos CLI); it does not ask for unrelated credentials or contact unknown external endpoints.

Purpose & Capability

Name/description match the actual behavior: scripts check for the sonos CLI, create a Python venv, install the soco library, and create a wrapper to run a playback Python script. Requiring the 'sonos' binary and installing soco are expected for Sonos+Netease playback.

Instruction Scope

SKILL.md instructs running local scripts (install.sh, check_env.sh, bootstrap_env.sh) and references only workspace, venv, wrapper, and playback script paths. It does not instruct collecting unrelated files, credentials, or sending data to external endpoints. Note: the actual playback Python implementation (sonos_netease_play.py) is not included and must be provided by the environment or overridden via OPENCLAW_SONOS_SCRIPT.

Install Mechanism

No external install spec; the bootstrap script uses pip to install the soco package from PyPI into a local venv. Installing from PyPI is expected for Python deps but does fetch remote packages (network activity) — this is normal but worth noting.

Credentials

No secrets or extraneous environment variables are requested. The scripts optionally honor OPENCLAW_* overrides and create a venv under $HOME by default; this is proportional to the stated goal.

Persistence & Privilege

The skill is not always-enabled and does not request elevated privileges. It will create a per-skill venv and wrapper script (under workspace or $HOME/.openclaw) which is normal for this functionality and limited to its own scope.

Assessment

This skill appears to do what it says: it checks for a Sonos CLI, creates a Python virtualenv, installs the soco library from PyPI, and writes a small wrapper script. Before installing, verify you trust the soco package source (PyPI) and the environment will allow network installs. Note the playback implementation sonos_netease_play.py is NOT included — you must supply or override it (OPENCLAW_SONOS_SCRIPT). The scripts use zsh and will create files under your workspace and $HOME/.openclaw by default. If you prefer a maintained option, the SKILL.md itself recommends the newer 'sonos-music-playback' skill.

Deprecated: this skill has been superseded by sonos-music-playback, which covers both 网易云音乐 and QQ音乐. Prefer the newer skill for fresh installs and future updates.

Overview

Use this skill as the portable, shareable version of the Sonos 网易云点播 workflow.

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 Netease music service authorization
• service availability may vary by region and by the user's linked Sonos music services

This skill should be designed toward simple installation:

• prefer one bootstrap command over many manual steps
• keep path assumptions configurable through environment variables
• minimize the number of places an agent must remember

This skill avoids machine-specific hardcoded paths by resolving from:

• OPENCLAW_WORKSPACE_DIR
• OPENCLAW_SONOS_VENV
• OPENCLAW_SONOS_WRAPPER
• OPENCLAW_SONOS_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
• wrapper defaults to ./scripts/sonos_netease_play.sh under the workspace
• playback script defaults to ./scripts/sonos_netease_play.py under the workspace

Quick Start

Preferred simple install:

./skills/sonos-netease-playback-market/scripts/install.sh

Manual flow if needed:

./skills/sonos-netease-playback-market/scripts/check_env.sh

If the check fails, run bootstrap:

./skills/sonos-netease-playback-market/scripts/bootstrap_env.sh

Then use the standard playback entrypoint, for example:

./scripts/sonos_netease_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
• the wrapper is missing or not executable

Bootstrap will:

• create the Sonos Python venv if missing
• install soco if missing
• create a default playback wrapper if the wrapper file is absent

Bootstrap does not install the sonos CLI. If sonos is missing, install or restore it separately.

4. Play through the standard wrapper

Do not call the Python playback file with system python3.

Prefer the wrapper because it pins the correct Python venv and avoids 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:

• convert the music service result into a Sonos-accepted object
• add_to_queue(...)
• play_from_queue(...)

This preserves Sonos App metadata such as:

• title
• artist
• album
• album art

Do not trust search titles alone

Netease 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

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 Netease service in Sonos App

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
• 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 the standard playback example
• 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 can generate a default playback wrapper when absent