{
  "schemaVersion": "1.0",
  "item": {
    "slug": "sonos-announce",
    "name": "Sonos Announce",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/clawdianova/sonos-announce",
    "canonicalUrl": "https://clawhub.ai/clawdianova/sonos-announce",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/sonos-announce",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=sonos-announce",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "sonos_core.py"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/sonos-announce"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/sonos-announce",
    "agentPageUrl": "https://openagent3.xyz/skills/sonos-announce/agent",
    "manifestUrl": "https://openagent3.xyz/skills/sonos-announce/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/sonos-announce/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Sonos Announce",
        "body": "Play audio files on Sonos speakers with intelligent state restoration."
      },
      {
        "title": "When to use",
        "body": "User wants to play an announcement on Sonos\nSoundboard effects (airhorn, rimshot, etc.)\nAny audio playback that should resume previous state\n\nThis skill handles playback only - audio generation (TTS, ElevenLabs, etc.) is separate."
      },
      {
        "title": "Quick Start",
        "body": "import sys\nimport os\nsys.path.insert(0, '/path/to/sonos-announce')\nfrom sonos_core import announce\n\n# Play audio and restore previous state\n# Assumes audio is in default media_dir (~/.local/share/openclaw/media/outbound)\nresult = announce('my_audio.mp3')"
      },
      {
        "title": "Installation",
        "body": "pip install soco\n\nRequirements:\n\npython3 - Python 3\nffprobe - Part of ffmpeg, for audio duration detection\nsoco - Python Sonos library"
      },
      {
        "title": "Core Function",
        "body": "announce(audio_file_path, wait_for_audio=True, media_dir=None)"
      },
      {
        "title": "Parameters",
        "body": "ParameterTypeDefaultDescriptionaudio_file_pathstrrequiredFilename (if using media_dir) or full path to audio filewait_for_audioboolTrueWait for audio to finish playing before returningmedia_dirstrNoneDirectory where audio file is located (HTTP server will serve from here)"
      },
      {
        "title": "Returns",
        "body": "{\n  'coordinators': 2,\n  'states': {\n    '192.168.1.120': {\n      'uri': 'x-sonos-spotify:spotify%3atrack%3a...',\n      'position': '0:01:23',\n      'queue_position': 5,\n      'was_playing': True,\n      'is_external': False,\n      'transport_state': 'PLAYING',\n      'speaker_name': 'Bedroom'\n    }\n  }\n}"
      },
      {
        "title": "Simple (file in default media directory)",
        "body": "from sonos_core import announce\n\n# File served from default media_dir\nresult = announce('announcement.mp3')"
      },
      {
        "title": "With custom media directory",
        "body": "from sonos_core import announce\n\n# Full path to audio file\nresult = announce(\n    'my_audio.mp3', \n    media_dir='/home/user/audio/announcements'\n)"
      },
      {
        "title": "Full path (no media_dir)",
        "body": "from sonos_core import announce\n\n# Uses directory of file as media_dir\nresult = announce('/full/path/to/audio.mp3')"
      },
      {
        "title": "Environment Variables",
        "body": "Configure the HTTP server for streaming to Sonos:\n\nVariableDefaultDescriptionSONOS_HTTP_HOSTauto-detectedLAN IP address (auto-detected)SONOS_HTTP_PORT8888HTTP server port\n\n# Set before running (optional)\nexport SONOS_HTTP_HOST=192.168.1.100  # Override auto-detected IP\nexport SONOS_HTTP_PORT=8888           # Override port\n\n# Or set in code before importing\nimport os\nos.environ['SONOS_HTTP_HOST'] = '192.168.1.100'\n\nfrom sonos_core import announce\nannounce('audio.mp3')"
      },
      {
        "title": "Supported Platforms",
        "body": "PlatformStatusNotesmacOS✅ SupportedFull supportLinux✅ SupportedFull supportWindows✅ SupportedUses taskkill and start /b\n\nThe module automatically detects your platform and uses appropriate commands for:\n\nKilling the HTTP server\nStarting the HTTP server in background"
      },
      {
        "title": "State Restoration",
        "body": "The module intelligently restores previous playback state:\n\nSource TypeBehaviorSpotify TrackResumed at exact position (seek)Spotify PlaylistResumed at exact position (seek)Spotify RadioResumed from start (no seek)Internet RadioResumed from start (no seek)Line-InRe-connected to Line-In inputTV/HDMIRe-connected to TV audioBluetoothRe-connected to BluetoothPaused contentLeft paused"
      },
      {
        "title": "Seeking Behavior",
        "body": "Some streaming services don't support seeking to a specific position:\n\nCan seek: Spotify tracks, Spotify playlists, local files, queue items\nCannot seek: Spotify Radio, TuneIn radio, Pandora, Tidal radio\n\nThe module automatically detects these and handles accordingly."
      },
      {
        "title": "External Input Detection",
        "body": "Automatically detects inputs that cannot be paused:\n\nx-rincon:RINCON_* - Line-In\nx-rincon-stream:RINCON_* - Line-In stream\nx-sonos-htastream:* - TV/HDMI (Sonos Home Theater)\nx-sonos-vanished:* - Vanished device\nx-rincon-bt:* - Bluetooth"
      },
      {
        "title": "Soundboard Example",
        "body": "from sonos_core import announce\n\nSOUNDS = {\n    'airhorn': '/path/to/sounds/airhorn.mp3',\n    'rimshot': '/path/to/sounds/rimshot.mp3',\n    'victory': '/path/to/sounds/victory.mp3',\n}\n\ndef play_sound(name):\n    \"\"\"Play a sound effect.\"\"\"\n    if name in SOUNDS:\n        announce(SOUNDS[name])\n    else:\n        print(f\"Unknown sound: {name}\")"
      },
      {
        "title": "Troubleshooting",
        "body": "IssueSolutionNo speakers foundEnsure on same network as Sonos speakersResume not workingCheck speakers were playing (not paused) before announcementHTTP server failedCheck port 8888 is available, or set SONOS_HTTP_PORTModule import errorRun: pip install socoDuration detection failsEnsure ffprobe is installed (part of ffmpeg)"
      },
      {
        "title": "Files",
        "body": "sonos_core.py - Main module with announce() function\nSKILL.md - This documentation"
      }
    ],
    "body": "Sonos Announce\n\nPlay audio files on Sonos speakers with intelligent state restoration.\n\nWhen to use\nUser wants to play an announcement on Sonos\nSoundboard effects (airhorn, rimshot, etc.)\nAny audio playback that should resume previous state\n\nThis skill handles playback only - audio generation (TTS, ElevenLabs, etc.) is separate.\n\nQuick Start\nimport sys\nimport os\nsys.path.insert(0, '/path/to/sonos-announce')\nfrom sonos_core import announce\n\n# Play audio and restore previous state\n# Assumes audio is in default media_dir (~/.local/share/openclaw/media/outbound)\nresult = announce('my_audio.mp3')\n\nInstallation\npip install soco\n\n\nRequirements:\n\npython3 - Python 3\nffprobe - Part of ffmpeg, for audio duration detection\nsoco - Python Sonos library\nCore Function\nannounce(audio_file_path, wait_for_audio=True, media_dir=None)\n\nParameters\nParameter\tType\tDefault\tDescription\naudio_file_path\tstr\trequired\tFilename (if using media_dir) or full path to audio file\nwait_for_audio\tbool\tTrue\tWait for audio to finish playing before returning\nmedia_dir\tstr\tNone\tDirectory where audio file is located (HTTP server will serve from here)\nReturns\n{\n  'coordinators': 2,\n  'states': {\n    '192.168.1.120': {\n      'uri': 'x-sonos-spotify:spotify%3atrack%3a...',\n      'position': '0:01:23',\n      'queue_position': 5,\n      'was_playing': True,\n      'is_external': False,\n      'transport_state': 'PLAYING',\n      'speaker_name': 'Bedroom'\n    }\n  }\n}\n\nUsage Examples\nSimple (file in default media directory)\nfrom sonos_core import announce\n\n# File served from default media_dir\nresult = announce('announcement.mp3')\n\nWith custom media directory\nfrom sonos_core import announce\n\n# Full path to audio file\nresult = announce(\n    'my_audio.mp3', \n    media_dir='/home/user/audio/announcements'\n)\n\nFull path (no media_dir)\nfrom sonos_core import announce\n\n# Uses directory of file as media_dir\nresult = announce('/full/path/to/audio.mp3')\n\nEnvironment Variables\n\nConfigure the HTTP server for streaming to Sonos:\n\nVariable\tDefault\tDescription\nSONOS_HTTP_HOST\tauto-detected\tLAN IP address (auto-detected)\nSONOS_HTTP_PORT\t8888\tHTTP server port\n# Set before running (optional)\nexport SONOS_HTTP_HOST=192.168.1.100  # Override auto-detected IP\nexport SONOS_HTTP_PORT=8888           # Override port\n\n# Or set in code before importing\nimport os\nos.environ['SONOS_HTTP_HOST'] = '192.168.1.100'\n\nfrom sonos_core import announce\nannounce('audio.mp3')\n\nSupported Platforms\nPlatform\tStatus\tNotes\nmacOS\t✅ Supported\tFull support\nLinux\t✅ Supported\tFull support\nWindows\t✅ Supported\tUses taskkill and start /b\n\nThe module automatically detects your platform and uses appropriate commands for:\n\nKilling the HTTP server\nStarting the HTTP server in background\nState Restoration\n\nThe module intelligently restores previous playback state:\n\nSource Type\tBehavior\nSpotify Track\tResumed at exact position (seek)\nSpotify Playlist\tResumed at exact position (seek)\nSpotify Radio\tResumed from start (no seek)\nInternet Radio\tResumed from start (no seek)\nLine-In\tRe-connected to Line-In input\nTV/HDMI\tRe-connected to TV audio\nBluetooth\tRe-connected to Bluetooth\nPaused content\tLeft paused\nSeeking Behavior\n\nSome streaming services don't support seeking to a specific position:\n\nCan seek: Spotify tracks, Spotify playlists, local files, queue items\nCannot seek: Spotify Radio, TuneIn radio, Pandora, Tidal radio\n\nThe module automatically detects these and handles accordingly.\n\nExternal Input Detection\n\nAutomatically detects inputs that cannot be paused:\n\nx-rincon:RINCON_* - Line-In\nx-rincon-stream:RINCON_* - Line-In stream\nx-sonos-htastream:* - TV/HDMI (Sonos Home Theater)\nx-sonos-vanished:* - Vanished device\nx-rincon-bt:* - Bluetooth\nSoundboard Example\nfrom sonos_core import announce\n\nSOUNDS = {\n    'airhorn': '/path/to/sounds/airhorn.mp3',\n    'rimshot': '/path/to/sounds/rimshot.mp3',\n    'victory': '/path/to/sounds/victory.mp3',\n}\n\ndef play_sound(name):\n    \"\"\"Play a sound effect.\"\"\"\n    if name in SOUNDS:\n        announce(SOUNDS[name])\n    else:\n        print(f\"Unknown sound: {name}\")\n\nTroubleshooting\nIssue\tSolution\nNo speakers found\tEnsure on same network as Sonos speakers\nResume not working\tCheck speakers were playing (not paused) before announcement\nHTTP server failed\tCheck port 8888 is available, or set SONOS_HTTP_PORT\nModule import error\tRun: pip install soco\nDuration detection fails\tEnsure ffprobe is installed (part of ffmpeg)\nFiles\nsonos_core.py - Main module with announce() function\nSKILL.md - This documentation"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/clawdianova/sonos-announce",
    "publisherUrl": "https://clawhub.ai/clawdianova/sonos-announce",
    "owner": "clawdianova",
    "version": "1.0.4",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/sonos-announce",
    "downloadUrl": "https://openagent3.xyz/downloads/sonos-announce",
    "agentUrl": "https://openagent3.xyz/skills/sonos-announce/agent",
    "manifestUrl": "https://openagent3.xyz/skills/sonos-announce/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/sonos-announce/agent.md"
  }
}