Sonos Cloud API - Better alerts & TTS

Just integrated this new integration, great work! The TTS audioclips play perfectly over the playing music, but with exact same volume as the music.

How can I adapt the volume for a TTS audio clip?

service: tts.cloud_say
  entity_id: media_player.front_room
  message: "Hello there"

Unfortunately not possible right now. The PR I created to fix this was rejected, so we’ll need to find a different approach.

I’m in the progress of migrating from Domoticz to HomeAssistant, and this is functionality that I had in Domoticz. I was able to play an audioclip to all speakers on a set volume, after the clip the media that was playing resumed on its original volume.

I used the http api below, I was then able to call http://localhost:5005/clipall/doorbell-2.mp3/55 for example which played the file on all sonos devices in sync with a volume of 55.

Maybe sombebody smart can integrate the functionality from this api into the HA integration?

That’s what the two previous comments were discussing. This is technically feasible but not currently possible with the current HA release. The suggested feature was not accepted.

You can do this today with a media_player custom component, but I wouldn’t recommend that.

Too bad. Hopefully something like this will be integrated in the feature. For people who are having the same issues, i’ve created a sort of workaround that works for me. I’ve installed the node-sonos-http-api that I mentioned before in a docker on my NAS. (you need to use the same network as the docker host for the way that the sonos speakers are discovered.) Then I created a very simple rest command to use the API (I only use it for MP3 and WAV files, so you can extend the rest command for other functionality of the API).

    url: "{{ file }}/{{ volume }}"

Now you can call the rest_command sonos_play as a service in automations with the data inputs:

service: rest_command.sonos_play
  file: "doorbell-2.mp3"
  volume: "55"

I wanted to use the same voice notifications as available in the companion app in IOS, that’s why I use wav and mp3 and no TTS. Now the notification plays perfect and the TV (with playbar) resumes with the orignal input and volume from the source (HDMI nvidia shield) after the notification.

Missed this message a while back. You can play an audio file at a specific volume with this integration–that’s the whole point. It uses a native single call to Sonos which will lower the volume for the current music and play the audio clip on top of it. One the clip is done playing, the music volume is restored the original level. At no point does the music stop playing.

The node-sonos-http-api method instead goes through multiple steps where it takes snapshots, stops music, plays the clip, (attempts to) restore the previous state, etc. That way has a chance of failing if playing music from certain streaming services.

The limitation I was talking about above where the volume can’t be set is specifically for tts.say_* service calls where you provide a text string to “speak” over the speakers.

Regarding v0.0.5

What exactly does this mean?
“Associates media_player entities with existing Sonos devices from the built-in integration.”

I currently have two media player entities for each actual media player e.g. and media_player.sonos_cloud_kitchen

Is this no longer necessary?

No, the redundant media_player is still necessary for now. The change in 0.0.5 just associates the sonos_cloud entity with the device created by the built-in sonos integration so all the entities for both will be displayed on the same speaker. It’s just a way to organize things a bit better.

1 Like

The 0.1.0 release adds support for stereo pair & home theater configurations with the new play_on_bonded parameter. Previously playback was limited to the “primary” speaker (left speaker in a pair, soundbar/amp in a HT setup).

This is accomplished by calling the API multiple times simultaneously and unfortunately does not guarantee synchronized playback (but it’s usually pretty close). Because of this, it’s not enabled by default.

Great addon, Thx! I tried it out my Arc calling the service from the developer tools using inbuilt the CHIME when nothing else was playing and it worked great. However, afterwards the Arc couldnt play sound from the TV, it didnt recognize the source at all, although the TV did recognize the Arc. I ended up having to factory reset.

Is this something you have seen before?


Sorry, I haven’t heard that reported before. Hopefully it was an unrelated fluke.

I try to install this integration from HACS. But it is not showing up in HACS under integrations. When I try to add the repository via HACS, I get an error that it already exists in the HACS store.

What am I doing wrong?

Update: it seems that it is not visible in my country (NL), when I change country filter to US, I do see it in the store. After installing it also works in my country. It is not clear to me why there is a country restriction on it.

Has anyone come up with an approach to this issue?

I haven’t posted an update in a while, but there have been a few new features added recently:

Added in 0.1.2:

  • Default volume support: This is handled by enabling the volume slider on the media_player entities. If set, all clips that that are played without an explicit volume parameter will use this slider volume. If set to 0 (the default) the clip will be played at the speaker’s actual current volume. Note: this slider only affects clip playback from this custom integration.

Added in 0.2.0:

  • Only supported on HA 2022.3.0 or newer (including the current beta!)
  • Media Browser support: This allows browsing local media and the new TTS interface. Can be opened using either the “Media” tab on the left, or by hitting the media browser icon in the bottom-right of a media control card.
  • Media Source support: This is a somewhat more advanced feature, but it allows you to provide special media_content_id URLs in scripts/automations to play local files or TTS messages. This will finally allow per-clip volume control of TTS messages!
  • Play Button support: This is mostly a workaround to ensure the Media Browser button is drawn correctly. Pressing the Play button will simply replay the previous clip. This may be removed in a future release. This was removed in 0.2.1.

Example of TTS volume control:

service: media_player.play_media
  media_content_id: media-source://tts/cloud?message=Hello there friend
  media_content_type: music
    volume: 35
1 Like

Thank you so much for the updates, loving the ability to set volume through the slider!

1 Like

Hi @jjlawren,

Just wanted to say thankyou for the brilliant work!

Today I’ve been playing with a few different integration types for Sonos and found they were too clunky for my needs. The ability to call a single action that: a) lowers the volume of current playing, b) plays a sound at a specific volume over the top, c) seamlessly return to increase original playing volume makes this a standout integration.

Its early days but it seems reliable so far. I havent tried text to speech yet but I’m already happy to have a usable doorbell sound. Best of luck with getting required changes to HA in order to integrate this better.

Thanks, Elton.


I am getting a weird error message when trying to use the plugin. Ideas would be appreciated!

When executing this:

service: media_player.play_media
  media_content_id: CHIME
  media_content_type: music

I get an error message:
Failed to call service media_player.play_media. Unknown error

Logs show:

Logger: homeassistant.helpers.script.websocket_api_script
Source: components/media_player/
First occurred: 9:34:51 PM (7 occurrences)
Last logged: 9:44:27 PM

websocket_api script: Error executing script. Unexpected error for call_service at pos 1: URL is relative, but does not start with a /
Traceback (most recent call last):
  File "/usr/src/homeassistant/homeassistant/helpers/", line 447, in _async_step
    await getattr(self, handler)()
  File "/usr/src/homeassistant/homeassistant/helpers/", line 680, in _async_call_service_step
    await service_task
  File "/usr/src/homeassistant/homeassistant/", line 1704, in async_call
  File "/usr/src/homeassistant/homeassistant/", line 1741, in _execute_service
    await cast(Callable[[ServiceCall], Awaitable[None]],
  File "/usr/src/homeassistant/homeassistant/helpers/", line 204, in handle_service
    await service.entity_service_call(
  File "/usr/src/homeassistant/homeassistant/helpers/", line 680, in entity_service_call
    future.result()  # pop exception if have
  File "/usr/src/homeassistant/homeassistant/helpers/", line 964, in async_request_call
    await coro
  File "/usr/src/homeassistant/homeassistant/helpers/", line 717, in _handle_entity_call
    await result
  File "/usr/src/homeassistant/homeassistant/components/media_player/", line 768, in async_play_media
    await self.hass.async_add_executor_job(
  File "/usr/local/lib/python3.9/concurrent/futures/", line 58, in run
    result = self.fn(*self.args, **self.kwargs)
  File "/usr/src/homeassistant/homeassistant/components/sonos/", line 67, in wrapper
    result = funct(self, *args, **kwargs)
  File "/usr/src/homeassistant/homeassistant/components/sonos/", line 616, in play_media
    media_id = async_process_play_media_url(self.hass, media_id)
  File "/usr/src/homeassistant/homeassistant/components/media_player/", line 46, in async_process_play_media_url
    raise ValueError("URL is relative, but does not start with a /")
ValueError: URL is relative, but does not start with a /

It looks like you’re using the built-in sonos integration. The sonos_cloud integration creates separate entities (for now).

I also think the format is incorrect, at least I have it different :slight_smile:

service: media_player.play_media
  media_content_id: CHIME
  media_content_type: music
  entity_id: media_player.livingroom_sonos_tts

Either format is valid. The entity_id needs to be updated.