sonos-announce

# 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

```python
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

```bash
pip install soco
```

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

## Core Function

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

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `audio_file_path` | str | required | Filename (if using media_dir) or full path to audio file |
| `wait_for_audio` | bool | True | Wait for audio to finish playing before returning |
| `media_dir` | str | None | Directory where audio file is located (HTTP server will serve from here) |

### Returns

```python
{
  '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)

```python
from sonos_core import announce

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

### With custom media directory

```python
from sonos_core import announce

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