External integration - Subsonic

Development
1

image
image800×534 43.7 KB

[Integration] Subsonic — Connect Gladys to Your Music Server (Navidrome, Airsonic…)

Hello everyone :wave:

I just published Subsonic, an external integration that connects Gladys to any music server implementing the Subsonic API: Navidrome, Airsonic-Advanced, Gonic, LMS, Subsonic…

My initial need was simple: I wanted Gladys to know what’s happening on my Navidrome instance and be able to trigger music from my scenes. It is developed and tested first against Navidrome, but nothing is specific to this server.

:link: Repository: GitHub - guim31/gladys-subsonic · GitHub

What It Brings

« Subsonic server » Device — 6 Sensors

Sensor What It Provides
Now playing The current track, in the format Artist — Title (listener)
Album cover The album cover of the music being played, refreshed with each track change
Active streams How many tracks are being played right now
Songs / Artists / Albums in library The size of your library

image
image676×578 80.5 KB

image
image673×772 56.7 KB

Display the Cover on the Dashboard

The cover uses Gladys’ image channel: add a Camera widget and choose the « Subsonic server » device. The widget name may seem surprising at first, but it’s the only one in Gladys that displays a device’s image and updates in real-time. The Photo widget, on the other hand, only accepts a fixed list of manually entered URLs: it cannot follow what’s playing.

« Subsonic jukebox » Device (Optional)

Control playback on the server side (jukebox function of the API): play/pause, previous/next, volume, and playback status. Must be explicitly enabled on both Gladys and the server side. The Music widget on the dashboard directly controls these commands.

Buttons in the Configuration Screen

  • Test connection — displays the server identity (e.g., navidrome 0.63.2, API 1.16.1)
  • Scan the music library
  • Jukebox: random play (N random tracks)
  • Jukebox: play a playlist (by name)

Some Scene Ideas

  • Do Not Disturb: if Active streams > 0, do not start the vacuum cleaner or turn off the speakers.
  • Wake Up to Music: at 7 a.m., the « play a playlist » action starts your morning playlist on the jukebox.
  • React to the Track: the « Now playing » sensor is a text feature, and Gladys triggers its scenes on the change of its value — you can therefore make your setup react to every new track (display the title, adjust the lights…).
  • Dashboard: the cover in large format (Camera widget), the current title, and the jukebox commands side by side.

Installation

Prerequisite: Gladys 4.86.0 or higher.

From Integrations → Install an Integration, search for « Subsonic » in the catalog.

Then, in the Configuration tab:

  1. Server URL: the root, without /rest — e.g., http://192.168.1.10:4533 (default port for Navidrome).
  2. Username / Password: an account from your server (create a dedicated one if possible).
  3. Authentication method: leave Token. The password never transits, only a salted md5 hash is sent. Switch to Legacy only for a very old server (API < 1.13) or an LDAP account that refuses the token.
  4. Click Test connection, then retrieve the device in the Discovery tab.

For the Jukebox

It plays music on the machine hosting the server (the one connected to your speakers). It must be enabled on both sides — in Navidrome:

[Jukebox]
Enabled = true

(or ND_JUKEBOX_ENABLED=true), then check Enable the jukebox device in the integration configuration.

What It Doesn’t Do (to Avoid Misunderstandings)

Let’s be clear about the limits, which come from the Subsonic API itself:

  • The jukebox plays on the server host, not on Gladys’ machine: this is not a multi-room solution.
  • Cannot control another client (your phone, the web player): the API does not allow controlling the playback of a third-party client.
  • No voice announcement via this integration: Gladys’ « Play a notification » action sends a TTS audio URL, but the Subsonic jukebox can only play tracks from the library. This remains the domain of Sonos / Chromecast.

Technical Side

Built from the official JavaScript template and the SDK @gladysassistant/integration-sdk. Node 24 Alpine, multi-arch image (amd64 + arm64), read-only rootfs, unit tests, and CI (Prettier / ESLint / tests) on every commit. Apache-2.0 license.

Special care was taken with the requests sent to the server: the complete list of artists is only re-read when the library has changed (scan signature) or once per hour, instead of being re-downloaded with each reading — the values are still published with each cycle. The cover follows the same logic: it is only downloaded when the track changes, and in the largest size that fits under the image channel limit.

Feedback, bug reports, and feature ideas are welcome, here or in the repository issues. If you try it with something other than Navidrome, I’d love to know if everything works well :slight_smile:

1 Like