External integration - Subsonic

[guim31]

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

Hello everyone

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.

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

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

[Tolkyen]

Hi @guim31, I wanted to know how to link the LMS I have with your integration. My LMS configuration does not require authentication, and it is mandatory in the integration. Is there a solution?

[guim31]

Hi @Tolkyen

Good news: it should work without changing anything, but you need to go through an API key.

It’s not the integration that’s too demanding: the Subsonic protocol carries credentials in every request, it simply doesn’t have an « unauthenticated » mode. And on the LMS side (if that’s indeed Lightweight Music Server you’re using), it’s even clearer — its documentation specifies that its Subsonic API only accepts API key authentication, regardless of the fact that your web interface doesn’t ask for anything.

Concretely:

1. In LMS, open the Settings page for your user and generate an API key.
2. In the Gladys integration configuration:
   • User : your LMS username
   • Password : the API key (not an account password)
   • Authentication method : leave Token
3. Click on Test the connection.

I checked in the LMS code: with the Token method, it calculates the salted hash of each of your user’s API keys and compares them to the one we send — so the default integration scheme works. If it ever gets stuck, switch to Legacy, LMS also handles this format.

One point of attention though: I only tested Navidrome. The jukebox in particular may behave differently — LMS has its own implementation. Your feedback interests me a lot, you would be the first on LMS

[Tolkyen]

I understand where my problem comes from, when I read LMS, I thought of Logitech Media Server and not Lightweight Music Server

[guim31]

Oh shoot… indeed it couldn’t work, Logitech Media Server isn’t based on the Subsonic API! You’ll have to ask for an integration for yourself

[prohand]

Hello,

Thanks for this integration
I’m installing it with a Navidrome server
I’ve created a dedicated user
The connection is fine but I get an error message on the scan:

I created a regular user without admin rights
I might have missed something but I don’t see what

I tested via the Token and Legacy methods and I get the same result

Thanks

[guim31]

Hi @prohand, thanks for the feedback

startScan is the only endpoint used by the integration that Navidrome reserves for administrators (it’s hardcoded in its Subsonic router). Since your dedicated user is a standard account, Navidrome refuses the operation — hence the error 50. That’s also why Jeton and Legacy give the same result: authentication works fine (your « Test Connection » is green), but authorization is what’s blocking it, and the authentication method doesn’t change that.

Two options:

• Do nothing — that’s what I recommend. This button is just a convenience shortcut: Navidrome already scans on its own (according to its scheduling and folder monitoring), and the integration’s sensors will follow at the next reading. No other functionality requires admin rights.
• Promote this account to administrator in Navidrome, if you really want to trigger the scan from Gladys.

Everything else works perfectly with a standard account: the sensors, the current track, the album cover, and even the jukebox (there, it’s Jukebox.Enabled on the server side that matters, not admin rights).

The real issue here is on my side: the message appears in green, like a success, when it’s actually a refusal — and it doesn’t explain the reason. I’ll fix that so it clearly appears as an error, with the cause. Thanks for reporting it!

[prohand]

Thanks for the feedback
I just checked and indeed I can see my server

Thanks

[prohand]

I don’t know if this is a bug or normal, but I just stopped the music on the Navidrome side and it tells me that there is still a song playing

[guim31]

For the music that remains displayed: this is not a bug, it’s the behavior of Navidrome’s « currently playing » list. A session is kept there after stopping — 30 minutes if the player reported a pause or stop, otherwise until the theoretical end of the track, because the classic Subsonic protocol has no notion of « stop »: a client simply stops asking for anything.

But I wasn’t taking advantage of information that Navidrome provides: the actual status of each session. This is fixed in the next version — only sessions actually playing are now counted, so your stop will be taken into account at the next update (max 60 s).

There will remain one irreducible case: a player that is closed without notifying the server remains listed until the end of the track. There, nothing can be done better.

And I also fixed the scan message: it now appears in red, with the explanation (admin rights) instead of a raw error code. Thanks for these two feedbacks!!

[prohand]

Thanks for the corrections