Sonos Announce

Play audio files on Sonos speakers with intelligent state restoration.

When to use

• User wants to play an announcement on Sonos
• Soundboard effects (airhorn, rimshot, etc.)
• Any audio playback that should resume previous state

This skill handles playback only - audio generation (TTS, ElevenLabs, etc.) is separate.

Quick Start

import sys
import os
sys.path.insert(0, '/path/to/sonos-announce')
from sonos_core import announce

# Play audio and restore previous state
# Assumes audio is in default media_dir (~/.local/share/openclaw/media/outbound)
result = announce('my_audio.mp3')

Installation

pip install soco

Requirements:

• python3 - Python 3
• ffprobe - Part of ffmpeg, for audio duration detection
• soco - Python Sonos library

Core Function

announce(audio_file_path, wait_for_audio=True, media_dir=None)

Parameters

Returns

{
  'coordinators': 2,
  'states': {
    '192.168.1.120': {
      'uri': 'x-sonos-spotify:spotify%3atrack%3a...',
      'position': '0:01:23',
      'queue_position': 5,
      'was_playing': True,
      'is_external': False,
      'transport_state': 'PLAYING',
      'speaker_name': 'Bedroom'
    }
  }
}

Usage Examples

Simple (file in default media directory)

from sonos_core import announce

# File served from default media_dir
result = announce('announcement.mp3')

With custom media directory

from sonos_core import announce

# Full path to audio file
result = announce(
    'my_audio.mp3', 
    media_dir='/home/user/audio/announcements'
)

Full path (no media_dir)

from sonos_core import announce

# Uses directory of file as media_dir
result = announce('/full/path/to/audio.mp3')

Environment Variables

Configure the HTTP server for streaming to Sonos:

# Set before running (optional)
export SONOS_HTTP_HOST=192.168.1.100  # Override auto-detected IP
export SONOS_HTTP_PORT=8888           # Override port

# Or set in code before importing
import os
os.environ['SONOS_HTTP_HOST'] = '192.168.1.100'

from sonos_core import announce
announce('audio.mp3')

Supported Platforms

The module automatically detects your platform and uses appropriate commands for:

• Killing the HTTP server
• Starting the HTTP server in background

State Restoration

The module intelligently restores previous playback state:

Seeking Behavior

Some streaming services don't support seeking to a specific position:

• Can seek: Spotify tracks, Spotify playlists, local files, queue items
• Cannot seek: Spotify Radio, TuneIn radio, Pandora, Tidal radio

The module automatically detects these and handles accordingly.

External Input Detection

Automatically detects inputs that cannot be paused:

• x-rincon:RINCON_* - Line-In
• x-rincon-stream:RINCON_* - Line-In stream
• x-sonos-htastream:* - TV/HDMI (Sonos Home Theater)
• x-sonos-vanished:* - Vanished device
• x-rincon-bt:* - Bluetooth

Soundboard Example

from sonos_core import announce

SOUNDS = {
    'airhorn': '/path/to/sounds/airhorn.mp3',
    'rimshot': '/path/to/sounds/rimshot.mp3',
    'victory': '/path/to/sounds/victory.mp3',
}

def play_sound(name):
    """Play a sound effect."""
    if name in SOUNDS:
        announce(SOUNDS[name])
    else:
        print(f"Unknown sound: {name}")

Troubleshooting

Files

• sonos_core.py - Main module with announce() function
• SKILL.md - This documentation