Home Assistant

The SnapDog integration shows your zones in Home Assistant as media players. It talks to the REST API and listens to the WebSocket API, so state changes appear without polling.

The integration lives in its own repository, SnapDogRocks/snapdog-homeassistant. It is not yet part of the HACS default list and not part of Home Assistant core. Until it is, you install it as a custom repository or copy it by hand. Both ways are supported.

What you get

• One media player per zone: play, pause, stop, next and previous, seek, volume, mute, shuffle and repeat, with title, artist, album, position and the playlist that is playing.
• A media browser with the playlists of the server and their tracks. You can also pick a playlist by name as the source of a zone.
• Search in the media browser for tracks, albums, playlists and radio stations, and covers in the browser, in search results and for the track on air.
• Actions to create, rename, fill, reorder and delete playlists on the media server (snapdog.create_playlist and five more). The server has to allow it with playlist_write = true in its [subsonic] section.
• One device for the server and one per zone. Entities are unavailable while the WebSocket is down, and the state is read again when it comes back.

Search, covers and the playlist actions need version 0.2.0 of the integration.

Clients as devices, the equalizer and speaker correction are not part of the integration yet.

Requirements

• Home Assistant 2026.10 or newer.
• SnapDog 0.31.0 or newer. The integration needs the stable playlist_id, the by-id playlist endpoints and the playlists_changed event from that release.
• Network access from Home Assistant to the SnapDog server (port 5555 by default).
• The API key, if you enabled Bearer authentication in snapdog.toml ([http].api_keys).

The integration installs its Python library pysnapdog from PyPI when Home Assistant loads it. The Home Assistant host therefore needs access to PyPI for the first start.

Install with HACS (custom repository)

This is the recommended way. HACS installs from the GitHub releases and shows updates.

1. Open HACS in Home Assistant, choose the menu in the top right and select Custom repositories.
2. Enter https://github.com/SnapDogRocks/snapdog-homeassistant as the repository and Integration as the type, then select Add.
3. Search for SnapDog in HACS, open it and select Download.
4. Restart Home Assistant.

Install by hand

Use this if you do not run HACS. You will not get update notices.

1. Download the source archive of the latest release from the releases page.
2. Copy the folder custom_components/snapdog into the custom_components folder of your Home Assistant configuration directory. Create that folder if it does not exist.
3. Restart Home Assistant.

Set up the integration

1. Go to Settings → Devices & services → Add integration and search for SnapDog.
2. Enter the host name or IP address of the SnapDog server, the port and, if you use one, the API key.
3. Confirm. Every zone becomes a media player, and the server becomes a device that the zones belong to.

Note

If you update SnapDog, update the integration too. The integration refuses servers older than its minimum version and says so in the setup dialog.

When the integration becomes official

Two steps are planned once enough people have used it: inclusion in the HACS default list, which makes the manual repository entry unnecessary, and later a proposal for Home Assistant core. Your settings and entities stay as they are in both cases. This page will describe the change when it happens.

Problems

Report problems at snapdog-homeassistant/issues and include the Home Assistant version, the SnapDog version and the log lines of the custom_components.snapdog logger.