[APP][Pro] Sonos (LocalAPI)

Apps
,
1

Hello everyone,

Sonos (LocalAPI) is a Homey Pro app for controlling your Sonos system directly over your local network. It does not rely on the Sonos cloud, so playback, volume changes and automations keep working locally and respond quickly.

This app started as a personal project because I wanted reliable local Sonos control in my own Homey setup. After using and improving it, I thought it might be useful for others as well, so I decided to make it publicly available.

It is my first Homey app, so please be nice :slight_smile: .

Why this app?

The official Sonos app uses cloud communication for many commands. That works fine in normal situations, but it also means control can become slow or unavailable when internet connectivity is limited.

Sonos (LocalAPI) talks to your speakers locally. This makes common actions such as playing URLs, changing volume, grouping speakers or triggering announcements noticeably faster and more dependable in local automations.

Key features

  • Local control of Sonos speakers
  • Play, pause, next, previous
  • Volume control, mute, shuffle and repeat
  • Track, artist, album, position, duration and album art
  • Group and ungroup speakers
  • Set group volume or adjust group volume relatively
  • Play Sonos favorites and Sonos playlists
  • Play URLs, announcements and Soundboard sounds
  • Text-to-speech announcements
  • TV input support for compatible Sonos home theater devices
  • Audio settings such as bass, treble and loudness
  • Home theater settings such as night sound, speech enhancement, subwoofer and surround options where supported
  • Flow triggers for playback, media changes, volume changes, group membership and audio input format changes
  • Option to ignore speakers that are offline or unreachable

Getting started

Install the app from the Homey App Store:

Live version: Sonos (LocalAPI) | Homey

Test version: Sonos (LocalAPI) | Homey

For the most reliable setup, it is recommended to give your Sonos speakers a fixed IP address in your router.

You can run this app alongside the official Sonos app if you want to compare behavior or migrate your flows gradually.

Notes

This app uses local Sonos APIs and is based on the node-sonos project, so credit goes to the maintainers of that library as well :folded_hands:.

Not every Sonos model supports every feature. Flow cards and settings that depend on specific hardware, such as TV input, subwoofer or surround options, are only useful when the speaker supports them.

Feedback and support

Questions, issues or feature requests are welcome in this topic. When reporting a problem, please include your Sonos model, app version, what you expected to happen and, if possible, a Homey diagnostics report.

2

Thanks for creating this app!

One observation: a have the habit of completely powering off my Sonos devices after user (due to the high standby power draw). I noticed that the device tile of the powered down device does not show the off/not playing state, but shows a red exclamation mark in the ‘on’ state.

Tapping the tile results in error message ‘Connection failed’. I assume because the app cannot find the (powered down) speaker anymore. Is this behavior as intended or should the device tile show the off/not playing state, without an exclamation mark?

IMG_2308
IMG_2308599×733 38.7 KB

3

This is expected behavior, but i’ve added a toggle in version 1.0.2 in the advanced settings of each speaker called “Ignore if offline/unreachable“. When that toggle is enabled it will just show not playing and ignore the error.

4

I did some additional testing in which I compared the behavior of this local app via the official cloud API app. Since I use the value of tags as input for some of my flows, I focused on them. To make the behavior of the two integrations more easily comparable, I created a dashboard that shows the media widget and capability/tag values for both integrations simultaneously.

Maybe Athom made some design choices in their app causing a different behavior. Other differences may represent a bug.

1 - The Playing (‘Afspelen’) tag always displays No in this integration, while in the official integration it shows Yes when playing and No when not playing.

2 - When starting a track via another controller (not Homey), the Album/Artist/Track tags are not updated and the Track tag shows technical ‘bump_sonic_pre_pre…’ content.

3 - Album art only updates when triggering a change in content (like a radio station) from Homey (not via the Sonos mobile app).

The following screenshot shows 1, 2 and 3

IMG_2320.HEIC
IMG_2320.HEIC1624×1186 237 KB

4 - When provided by the music source, in the official integration the Album tag shows the online service name (like Sonos Radio) and the Artist tag the radio station name (if the artist is not provided separately, but as part of the track name). Both are not displayed in the local integration.

IMG_2316.HEIC
IMG_2316.HEIC1549×1257 306 KB

IMG_2321.HEIC
IMG_2321.HEIC1641×1178 242 KB

5 - When playback is stopped (via pause button), the official integration keeps showing the online service name (like Sonos Radio) in the Album tag, but this integration shows the radio station name in the Track tag. The radio station name is not shown while playing, though it seems to be available. Also the album art is not cleared in the local app.

IMG_2317.HEIC
IMG_2317.HEIC1558×1150 208 KB

6 - When switching the source of my Playbar to the TV input, the cloud app reflects this by displaying ‘TV Audio’ in the Track tag. This integration however shows the technical ID of the Playbar (RINCON_…) in the Track tag. Also the album art is not cleared.

IMG_2323.HEIC
IMG_2323.HEIC1646×1190 216 KB

7 - The Length tag is not cleared when a song is played for which no length is provided (like a radio station). It keeps the length value of the prior song for which a length value was available.

IMG_2324.PNG
IMG_2324.PNG1597×1169 230 KB

5

Unfortunately I am unable to install this version, as it keeps crashing. I have tried removing the app completely, but it crashes directly upon starting up.

IMG_2325.PNG
IMG_2325.PNG1160×794 50.2 KB

Diagnostic report after reinstalling the app: c041a116-e5dc-4471-b3da-8ad7f36283d7.

6

Are you able to test v1.0.3? This version should fix the crash.

Thanks a lot for the extensive testing and the feedback! I’ll recreate the dashboard and compare the behavior and fix where necessary.

Let me know if the crash is gone or if you run into anything else :slightly_smiling_face:

7

Yes, the app is up and running again! Thanks for the quick fix.

8

Sorry for spamming you :blush:. Some additional observations regarding the Shuffle and Repeat function.

When playing music for which repeat/shuffle is not available, like playing a radio station, tapping the Repeat of Shuffle button results in an error message.

Repeat:

IMG_2326
IMG_23262420×1425 338 KB

Shuffle:

IMG_2329
IMG_23292420×1454 320 KB

Note that the official cloud integration allows you to click those buttons and enable those functions, without doing anything of course. Which is also not what you want, but at least it does not cause an error.

9

No spam at all! It’s very helpful feedback. You should now be able to press the buttons without error messages. Below are my comments on the issues you mentioned.

10

Thanks for the update! I checked the changes.

This items are resolved
1 - The Playing (‘Afspelen’) tag now changes depending on the player state :white_check_mark:.

2 - Homey now updates the speaker widget/tags when I use an external controller and the technical message is now gone :white_check_mark:.

3 - Album art now update, though some time directly after updating to the new app version, the album art stayed empty. Seems to have resolved itself :white_check_mark:.

6 - When switching to the TV input, the Track tag now shows ‘TV/HDMI’ :white_check_mark:. I think this is fine, though my Playbar uses an optical input (the TV-part applies in my case). I think the newer soundbars use HDMI. Further, some Sonos devices have a traditional line in (jack). Not sure how switching to that input is displayed (I cannot test that, as I do no have a device with such an input).

These items may need some further attention
4 - This now always shows a fixed label ‘Radio’ in the Track tag and the station name in the Artist tag, when playing a radio station sourced by TuneIn. However I expect it to dynamically display the online service name, if available/provided (like ‘Sonos Radio’). Also, the track and artist info is not shown. Further, when I use Sonos Radio as a service (instead of TuneIn), this ‘Radio’ label is not shown, instead the actual artist and track info is shown. So this does not seem to work consistently :cross_mark:. Also see below my remark on the Album, Artist, Track tags.

5 - The Track / Artist / Album tags and album art are cleared now :white_check_mark:, but I noted that the Position and Length tags are not :cross_mark:.

7 - In my case the Length tag sometimes keeps the value of the prior song and is not cleared when switching to e.g. an online radio station (that, I assume, does not provide length info). I haven’t figured out yet in which cases this tag is cleared and when not :cross_mark:.

Analysis of Album, Artist, Track tags used in Homey and the official Sonos integration
There are three main tags available for displaying music info: Album, Artist and Track. These are also the ones Homey uses to populate the speaker widget. This works fine for local music, that have exactly there three tags.

However when steaming music from an online service (in my case radio stations), there are actually two more pieces of information: the name of the online service and the radio station name. Since there are only three tags available, the additional info is put into or combined with the other information in the three main tags (Album, Artist and Track).

I am not sure if it is the Sonos API that decides how this extra information is included in the three main tags, or it is a design choice by Athom in the official Sonos app. I assume it’s a combination. Regardless, it seems to be applied consistently depending on the scenario.

I made the following overview that shows the scenarios and how the three main tags are populated in the official Sonos app (based on my observations):

Sonos Tags
Sonos Tags1548×1045 111 KB

Looking at the image, the first two groups of sources (local music and physical input) are already covered by your app. The last group (online service) are handled differently sometimes in your app. Also see my earlier remark on item 4.

Ideally I would like your app to mimic the behavior of the official app, which results in all available info being displayed by combining it - when necessary - in the available tags. But I can imagine that you have also your own thoughts on this matter. Whichever option: it would be nice if also the name of the online service and radio station name are included somehow in the available tags in a consistent manner, without losing the album/artist/track info.

11

I’ve published v1.0.7 which contains some bugfixes and it’s now listening to events instead of polling for updates. I also did some work on how album, artist and track are displayed but I need some more time for that. For now I have broken the displaying of the radio station.

It now shows Sonos Radio or TuneIn in the album tag.

The “problem” is that we only have Track, Artist and Album to play with. Now the Track and Artist are shown correct. The official app combines artist and track into the Track tag and shows the station in the Artist field. I’m not sure if that’s the way to go, what do you think?

12

Maybe it’s an idea to use the Album tag to show the music service name and radio station (when available). Before the official app showed the music service, I suggested to Athom to use the Album tag for that, as it was empty when listening radio. They chose otherwise, but the Album tag sounds more logical to me. If I am correct you are suggesting the same.

I installed the latest test version. It seems that - for radio stations - the track and artist are not displayed. See the example of Radio 10 Non-Stop being played via Sonos Radio righthand side). The Artist tag shows the station name and the Track tag the music service.

IMG_2366
IMG_23661579×989 105 KB

But perhaps that is the part you’re still working on :blush:.

13

Hmm just tried Radio 10 Non-Stop (Sonos Radio) and had the same behavior. After that tried Sky Radio (Tune-In) that worked fine. So tried Sky Radio from Sonos Radio and the track/artist info is gone. So there is a difference in data received from the streaming services. After adding some logging i think i’ve found the issue.

Can you try v1.0.8? This should show the station name under Album and show correct track information for Sonos Radio and Tune In.

(I noticed that after updating I have to kill the Homey app to get the updated album art)

14

Yes, its working now :grinning_face:.
I see both the track, artist and station name (latter in the Album tag).

One minor observation: while connecting and while the commercials are played when starting a radio station, the Track tag shows a technical message ‘ZPSTR_CONNECTING’. Not sure whether you want to hide that message:

IMG_2367
IMG_23671610×979 121 KB

15

Cool. The delay in the current app is annoying, so this could be great. Will test. Ismit possible to have both apps running? no need to uninstall the current Sonos app?

16

Some additional observations.

Artwork
Apparently some music services (like Sonos Radio) provide multiple album artworks. See the below example. The official app shows the artwork specific to the track being played; your app shows the artwork of the radio station. Perhaps it is possible to add a setting in your app to have the user set which of the two should be displayed?

IMG_2370.PNG
IMG_2370.PNG1578×981 165 KB

Flowcards
I did a comparison of available flowcards between the official app and yours. Regarding the THEN cards I noted some differences (based on my Sonos Playbar). The following cards are not available in your app:

Flowcard (in Dutch)
Zeg (Tekst) op volume (Volume)
Speel geluid (Geluid) op volume (Volume)
Speel de (Afspeellijst) afspeellijst
Speel URL (URL) op volume (Volume)
Speel Soundboard geluid (Geluid) op volume (Volume)
Stel bron in op TV
Zet groepsvolume naar (Bereik)

Especially the latter two cards are relevant (in my case) (a) in order to set the source of my Playbar to the optical input to which the TV is connected and (b) to set the group volume for all grouped players at once, instead of setting the volume per player. Maybe other users also use the other cards.

17

You can have both apps running simultaneously, as you can see in my screenshots in which I compare the speaker widget and tags side by side :grinning_face:.

18

Will test with the album art. In v1.0.10 I have added the switch to TV input. It works for my Arc Ultra, but can you test it with the Playbar? Not sure if it works there too.

Also added two flow cards to set group volume and set relative groupvolume.

19

I have installed v1.0.12, but I cannot find the flowcard to switch source to the TV input. Not sure why not.

I do see the two new cards related to the group volume.

20

I have just released 1.0.13 hopefully with a fix for the playbar detection. If that doesn’t work either, could you send me the output when you go to http://PLAYBAR_IP>:1400/xml/device_description.xml