Skip to main content

Subsonic smart home integration, free and open source

Subsonic integration for Gladys Assistant

Link Gladys with a Subsonic-compatible music server: Navidrome, Airsonic, Gonic...

View on GitHubAll external integrations

This integration links Gladys Assistant with any music server implementing the Subsonic API: Navidrome, Airsonic-Advanced, Gonic, LMS, Subsonic… It was designed and tested first against Navidrome.

What you get​

  • A Subsonic server device with five periodically refreshed sensors, usable in your scenes and on your dashboard:
    • Now playing: the track being played right now, as Artist — Title (listener). Gladys fires its scene triggers when this value changes, so you can react to every new track;
    • Active streams: how many songs are being played right now (handy for a "don't cut the sound while someone is listening" scene);
    • Album cover: the artwork of the album being played. It travels on the Gladys image channel, so it shows up in the dashboard Camera widget (pick the "Subsonic server" device). When playback stops the last cover stays on screen; until anything has ever been played, a neutral placeholder takes its place;
    • Songs, Artists and Albums counted in the library.
  • An optional Subsonic jukebox device to control server-side playback: play/pause, previous/next, volume and playback state.
  • Buttons in the Configuration screen: test the connection, start a library scan, play random songs or a playlist on the jukebox.
  • Three dashboard widgets (Gladys 5.1 or later): Now playing, Jukebox and Library — see below.

Configuration​

  1. Open the Configuration tab of the integration.
  2. Fill in:
    • Server URL: the root of your server, without /rest — for example https://music.mydomain.com or http://192.168.1.10:4533 (Navidrome's default port);
    • Username and Password: an account on your server. Prefer a dedicated account for Gladys;
    • Authentication method: keep Token (the password never transits, only a salted md5 hash is sent). Switch to Legacy only for very old servers (API < 1.13) or LDAP accounts that reject tokens (error 41);
    • Refresh interval: how often the sensors are polled (60 s by default).
  3. Save, then click Test the connection: the server answers with its name and version (for example navidrome 0.52).
  4. The devices show up in the Discovery tab, ready to be added.

The jukebox (server-side playback)​

Jukebox mode plays the music on the machine hosting the server (the one wired to your speakers), through the jukeboxControl API endpoint. It must be enabled on both sides:

  1. Server side. For Navidrome, in navidrome.toml:

    [Jukebox]
    Enabled = true

    or with the ND_JUKEBOX_ENABLED=true environment variable. The host needs a working audio output (see the Navidrome jukebox mode documentation).

  2. Gladys side. Turn on Enable the jukebox device in the integration configuration: the "Subsonic jukebox" device then appears in discovery.

From your scenes or the dashboard you can then: play/pause, skip to the next or previous track, set the volume, and trigger the Play random songs (N random tracks) or Play a playlist (by exact name, case-insensitive) buttons.

Dashboard widgets​

With Gladys 5.1 or later, the integration offers three widgets (Edit the dashboard → Add a widget). They have no settings: each one follows the configured server. The number tiles are bound to the sensors of the "Subsonic server" device: add it to Gladys for them to show a value.

  • Now playing — the number of streams in progress (the tile follows the sensor live) and one row per session the server lists: title, artist · album, the cover, and as a badge the listener name (or else the player name), green when the session really plays, grey when it is paused or stopped (the server keeps a session listed for a while after it stops). Eight rows at most, the active streams first. Nothing playing: "Nothing is playing right now." Refreshed every 30 seconds; the list read by the periodic poll is reused while it is less than 30 seconds old.
  • Jukebox — the server-side playback as a remote: the cover and the title of the current track, artist · album, then the state (Playing / Stopped), the volume and the position in the queue ("2 / 20"), and four buttons: Pause or Play depending on the state, Previous, Next and Shuffle (20 random songs, like the configuration button). An empty queue only offers Shuffle. Until the jukebox device is enabled in the configuration, the widget says so. Refreshed every 30 seconds, and as soon as a button acted. The buttons work even if the "Subsonic jukebox" device was not added to Gladys; the playback state published to Gladys follows every command.
  • Library — three live tiles (Songs, Artists, Albums), the server identity (type and version returned by the ping, for example navidrome 0.53.3), the scan status ("Running · n" or "Done · n songs"; "Unavailable" when the server refuses getScanStatus to this account) and a Scan button. Refreshed every 15 minutes, every 10 seconds during a scan. The button is subject to the same rights as the configuration one: Navidrome reserves scans to administrators.

The widget covers are served by the integration (asked to the server at 300 px) and cached one hour by Gladys. A track without a cover shows without an image.

Troubleshooting​

  • "Wrong username or password" (error 40): double-check the credentials by logging into the server's web interface.
  • Error 41: your account (often LDAP) does not accept token authentication — switch the method to Legacy.
  • "Cannot reach the Subsonic server": make sure the URL is reachable from Gladys (same machine/network as the integration container), not only from your browser.
  • The jukebox makes no sound: the audio comes out of the server host, not the device running Gladys. Check Jukebox.Enabled and the host's audio output (audio device access for a Docker container, if applicable).
  • The sensors show "no recent value": the integration reads the server itself as soon as the device is added, then at the chosen interval (60 s by default), whatever Gladys' own polling does. If the values stay empty, the server does not answer: Test the connection says why, and the integration logs say it once (and once more when it answers again). A value that does not change is only sent again every 12 hours.
  • "The server refuses a scan from this account": starting a scan is reserved to administrators (Navidrome does so). It does not matter: the button is only a shortcut, the server scans on its own schedule and the sensors follow. Make the account an administrator if you want the button — nothing else in the integration needs those rights.
  • A track stays on screen although playback stopped: the server keeps the session in its "now playing" list for a while after the music stops. The integration only counts sessions whose reported state is really playing, but a player that simply goes silent without telling the server (the classic Subsonic protocol has no notion of stopping) stays listed until the track would have ended.
  • The sensors never change: the artist/album counters only move after a library scan — use the Scan the music library button.

Configuration settings​

These are the settings Subsonic asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Server connectionsectionNoWorks with any server implementing the Subsonic API (Navidrome, Airsonic-Advanced, Gonic...). Use a dedicated user account if you can. The URL is the root of the server, e.g. https://music.example.com or http://192.168.1.10:4533.
Server URLstringYesRoot URL of the Subsonic server, without /rest.
UsernamestringYes
PasswordsecretYes
Authentication methodselectNoToken (md5 + salt) is supported by every modern server. Use legacy only for pre-1.13 servers or LDAP users.
Refresh interval (s)numberNoHow often the server sensors are polled, in seconds. Gladys only supports 10, 15, 30 or 60 s: the value is snapped to the closest one.
Jukebox (server-side playback)sectionNoThe jukebox plays music on the machine hosting the server. It must also be enabled server-side: in Navidrome, set Jukebox.Enabled = true (ND_JUKEBOX_ENABLED=true) and make sure the host has an audio output.
Enable the jukebox devicebooleanNo

How to install Subsonic in Gladys​

  1. In Gladys, open Integrations: Subsonic appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-subsonic:1.2.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-subsonic.

Subsonic requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Subsonic is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on