SoCo (Sonos Controller)

0.31.0 verified Fri May 01 auth: no python

SoCo is a Python library for controlling Sonos speakers. It provides a simple interface to discover, query, and control Sonos devices over a local network. Current version 0.31.0 supports Python >=3.6, with releases approximately every few months.

pip install soco

Common errors

error AttributeError: module 'soco' has no attribute 'SoCo' ↓

cause Incorrect import: using `import soco` and then `soco.SoCo()` is wrong.

fix

Use from soco import SoCo or import soco; soco.SoCo

error soco.exceptions.SoCoException: No response from the device ↓

cause Speaker IP is wrong or speaker is not reachable on the network.

fix

Verify the IP address and network connectivity. Use ping or discovery methods.

error TypeError: play_uri() got unexpected keyword argument 'meta' ↓

cause Using deprecated `meta` parameter in SoCo v0.30+.

fix

Replace meta with title and/or metadata keyword arguments.

Warnings

gotcha SoCo only works on the same local network as Sonos speakers. It does not support cloud control or remote access. ↓

fix Ensure your script runs on a machine connected to the same LAN as the Sonos speakers.

gotcha Speaker IP addresses can change (DHCP). It is recommended to use discovery methods like `soco.discover` instead of hardcoding IPs. ↓

fix Use `discover()` to find speakers dynamically: `from soco import discover; speakers = discover()`

breaking In v0.30.0, the `play_uri` method signature changed: the `meta` parameter was removed and `title` and `metadata` parameters were added. ↓

fix Update calls: `speaker.play_uri(uri, title='My Stream')` instead of `speaker.play_uri(uri, meta=...)`

Imports

SoCo
wrong
```
import soco
```
correct
```
from soco import SoCo
```
SoCo is a class, not a module

Quickstart

Quickstart: import SoCo, create instance with IP, control playback, volume, and get track info.

from soco import SoCo

# Discover a speaker by IP (replace with your speaker's IP)
speaker = SoCo('192.168.1.10')

# Play music (e.g., a URI)
speaker.play_uri('x-rincon-mp3radio://stream.example.com:8000/stream')

# Adjust volume
speaker.volume = 30

# Get current track info
track = speaker.get_current_track_info()
print(track.title)