🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Sonos Netease Playback
πŸ¦€ ClawHub

Sonos Netease Playback

by @huacius

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...

Versionv0.1.1
Downloads343
#clawhub
TERMINAL
clawhub install sonos-netease-playback

πŸ“– About This Skill

name: sonos-netease-playback description: 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 a Sonos room, preserve Sonos App metadata display, bootstrap the Python SoCo dependency, or restore the environment after migration. Suitable for packaging or sharing because it avoids machine-specific hardcoded paths and uses environment variables for workspace, wrapper, script, and venv resolution. metadata: { "openclaw": { "requires": { "bins": ["sonos"] }, "install": [ { "id": "soco-python-venv", "kind": "message", "label": "Run the skill bootstrap script to create the Sonos Python venv and install soco", }, ], }, }

Sonos Netease Playback

> 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

    πŸ’‘ Examples

    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' 'θ‡³ε°‘θΏ˜ζœ‰δ½ '

    πŸ“‹ Tips & Best Practices

    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.