pysnapdog 0.1.0

pysnapdog: async Python client for the SnapDog multi-room audio server

Typed. Fully asynchronous. Built for Home Assistant, usable everywhere.

pysnapdog talks to a SnapDog server over its REST API and, as the library grows, over its WebSocket. It is the client library behind the SnapDog integration for Home Assistant, and it has no Home Assistant dependency of its own: you hand it an aiohttp session and it hands you typed objects.

Features

Installation

pip install pysnapdog

Requires Python 3.14 or newer, the version Home Assistant 2026.10 runs on.

Quick start

import asyncio

import aiohttp

from pysnapdog import SnapDogClient


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        client = SnapDogClient(session, "snapdog.local", api_key="…")

        version = await client.version()
        print(f"{version.name} {version.version}")

        for zone in await client.zones():
            print(f"{zone.index}: {zone.name} ({zone.playback}, volume {zone.volume})")


asyncio.run(main())

api_key is only needed when the server has api_keys configured. For a server behind TLS pass tls=True, and verify_tls=False for a self-signed certificate.

Control a zone

Indexes of zones and clients start at 1, as in the server's API. Zone commands return nothing, the new state arrives as an event. Calls on clients return the new value.

await client.set_zone_volume(1, 35)  # absolute, or "+5" / "-3" for relative
await client.play_playlist(1, playlist=2)
await client.set_zone_repeat(1, RepeatMode.PLAYLIST)
await client.apply_zone_eq_preset(1, "rock")
await client.set_client_zone(3, 2)  # move client 3 into zone 2
cover = await client.zone_cover(1)  # Image(content=b"...", content_type="image/jpeg")

Live updates

The server sends no initial state. SnapDogListener opens the socket first, lets you read the state over REST, and only then delivers the events that arrived meanwhile, in order. It does the same again after every reconnect.

from pysnapdog import SnapDogListener, ZoneChanged, ZoneVolumeChanged

zones: dict[int, Zone] = {}


async def load() -> None:
    zones.update({z.index: z for z in await client.zones()})


async def on_event(event) -> None:
    if isinstance(event, ZoneVolumeChanged):
        print(f"zone {event.zone}: volume {event.volume}, muted {event.muted}")


listener = SnapDogListener(client, on_event=on_event, on_connected=load)
listener.start()  # from a running event loop
...
await listener.stop()

Events carry absolute values, never a delta. A client that falls behind is closed by the server with code 1013, and the listener reconnects and calls on_connected again. A rejected API key ends the listener, because retrying cannot help: the error is in listener.stopped_reason.

Errors

from pysnapdog import (
    SnapDogAuthError,
    SnapDogConnectionError,
    SnapDogError,
    SnapDogUnsupportedError,
)

try:
    eq = await client.client_eq(3)
except SnapDogAuthError:
    ...  # the key is missing or wrong
except SnapDogUnsupportedError:
    ...  # HTTP 422: the client is not a SnapDog client, so it has no EQ
except SnapDogConnectionError:
    ...  # the server is away, or the connection broke off
except SnapDogError:
    ...  # anything else the library raises

SnapDogResponseError carries status and the server's own message in detail.

What is covered

The server has 100 REST operations. Every one is either a library call that a test exercises, or on a short list of single-field reads that the Zone, Client, TrackMetadata and ZonePlaylist models already carry. scripts/check_coverage.py compares the library with the pinned openapi.json and asyncapi.json and fails when an operation or event is neither covered nor excluded with a reason. CI runs it, so the gap cannot grow unnoticed.

Development

The project uses uv.

git clone https://github.com/SnapDogRocks/pysnapdog.git
cd pysnapdog
uv sync

uv run ruff check .          # lint
uv run ruff format --check . # format
uv run mypy                  # types, strict
uv run pytest --cov          # tests, coverage floor 95 %
uv run python scripts/check_coverage.py   # every operation and event of the server

Commits follow Conventional Commits. A local hook checks them once you run lefthook install (see CONTRIBUTING.md).

Related projects

• SnapDog — the server this library talks to.
• snapdog-homeassistant — the Home Assistant integration built on this library (in preparation).

License

Apache License 2.0.