soco

library0.31.1pypypi✓ verified 84d ago

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.

communication http-networking

pip install soco

github ↗package ↗

INSTALL

IMPORT

SIG · SOCO

soco

communicationpythonv0.31.1

Install

2.9s avg

Import

921ms

Disk

33MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.31.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.978s · 34.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.9s · import 0.864s · 35MB

33MB installed

● package 33MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SoCo

✓ from soco import SoCo

✗ import soco

SoCo is a class, not a module

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)

Debug

Known issues

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

affects: all

gotchaSpeaker 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()`

affects: all

breakingIn 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=...)`

affects: >=0.30.0

Errors

Common errors & fixes

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

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

fix

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

soco.exceptions.SoCoException: No response from the device

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.

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

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

fix

Replace `meta` with `title` and/or `metadata` keyword arguments.

Upgrade

Version history

0.31.1latest on PyPI · released May 25, 2026

Audit

Dependencies

requestsrequiredHTTP requests to Sonos devices

urllib3requiredUsed internally for HTTP

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/SoCo/SoCo ↗

packagehttps://pypi.org/project/soco/ ↗