pysnapdog 0.3.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_id(1, "subsonic:42")  # remember playlists by playlist_id, not by index
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")

A playlist has a stable playlist_id (snapdog:radio or subsonic:<id>) and a unified index that moves when playlists or radios are added or removed. Store and compare the playlist_id, and reload client.playlists() on the PlaylistsChanged event and after a reconnect. Against a server that is too old to send playlist_id, it is None and the models take index from the deprecated id field.

Search and manage playlists

Search needs a Subsonic server behind SnapDog. limit and offset apply to each kind, and every result has the identifier of its own kind. Writing playlists needs [subsonic].playlist_write = true on the server, otherwise the calls raise SnapDogReadOnlyError. Address a playlist by its playlist_id.

from pysnapdog import SearchKind

result = await client.search("elton", kinds=[SearchKind.ALBUM, SearchKind.TRACK], limit=10)
for item in result.items:
    print(item.kind, item.title, item.subtitle)
await client.play_subsonic_album(1, result.items[0].album_id)  # an album plays as its own queue
cover = await client.media_cover(result.items[0].cover_id)

playlist = await client.create_playlist("Evening", ["track-id-1", "track-id-2"])
await client.update_playlist(playlist.playlist_id, name="Late", add_track_ids=["track-id-3"])
await client.replace_playlist_tracks(playlist.playlist_id, ["track-id-3", "track-id-1"])
await client.delete_playlist(playlist.playlist_id)

The server refuses snapdog:radio with the same SnapDogReadOnlyError, because that list lives in its configuration file. When the Subsonic server itself says no, for example for a user without the right to edit, the error is SnapDogUpstreamError with its message in detail.

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,
)  # also SnapDogReadOnlyError (403) and SnapDogUpstreamError (502), see above

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