Sonos Cloud integration for Home Assistant
The sonos_cloud integration uses the cloud-based Sonos Control API to send audioClip commands to speakers. This allows playback of short clips (e.g., alert sounds, TTS messages) on Sonos speakers without interrupting playback. Audio played in this manner will reduce the volume of currently playing music, play the clip on top of the music, and then automatically return the music to its original volume. This is an alternative approach to the current method which requires taking snapshots & restoring speakers with complex scripts and automations.
This API requires audio files to be in .mp3 or .wav format and to have publicly accessible URLs.
Easy: Use HACS and add the Sonos Cloud Integration.
Manual: Place all files from the sonos_cloud directory inside your <HA_CONFIG>/custom_components/sonos_cloud/ directory.
Both methods will require a restart of Home Assistant before you can configure the integration further.
You will need to create an account on the Sonos Developer site, and then create a new Control Integration. Provide a display name and description, provide a Key Name, and save the integration. It is not necessary to set a Redirect URI or callback URL. Save the Key and Secret values for the integration configuration.
** Click here if using Home Assistant 2022.5 or below **
Older versions of Home Assistant do not support setting application credentials in the frontend.
Add an entry to your configuration.yaml using the Key and Secret from your Sonos app:
sonos_cloud:
client_id: <YOUR_APP_KEY>
client_secret: <YOUR_APP_SECRET>You will need to restart Home Assistant if adding credentials while already running.
Note: This is no longer necessary in 2022.6 and later with Sonos Cloud release 0.3.0.
On the Integrations page in Home Assistant, add a new "Sonos Cloud" integration. You will need to first provide your application credentials obtained from the Sonos Developer site above. The Key should be used as the Client ID, and the Secret as the Client Secret.
You will then be redirected to the Sonos website to login with your "normal" Sonos username and password (not your Sonos Developer login). You will receive a prompt saying "Allow <YOUR_APP_NAME> to control your Sonos system". Accept this and the integration will complete configuration.
The integration will create new media_player entities for each Sonos device in your household. You must reference these new media_player entities in order to use the tts.<platform>_say and media_player.play_media services to play the clips.
Support for browsing and playing back local audio clips using the Media Browser is supported. Media Source URLs for local media and TTS can also be provided to media_player.play_media.
The playback volume can be set per audio clip and will automatically revert to the previous level when the clip finishes playing. The volume used is chosen in the following order:
- Use
data->extra->volumeif provided in themedia_player.play_mediacall. - Use the volume on the
media_playerentity created by this integration. This default can be disabled by setting the volume slider back to 0. Note that this volume slider only affects the default audio clip playback volume. - If neither of the above is provided, the current volume set on the speaker will be used.
Note: Volume adjustments only work with the media_player.play_media service call. For TTS volume control, use media_player.play_media with a Media Source TTS URL (see below).
Service calls to media_player.play_media can accept optional parameters under data->extra:
volumewill play the clip at a different volume than the currently playing musicplay_on_bondedwill play on all bonded speakers in a "room" (see notes below)
service: media_player.play_media
data:
entity_id: media_player.kitchen
media_content_id: https://<unique_cloud_id>.ui.nabu.casa/local/sound_files/doorbell.mp3
media_content_type: music
extra:
volume: 35 # Can be provided as 0-100 or 0.0-0.99
play_on_bonded: trueMedia Source URLs are supported:
service: media_player.play_media
data:
entity_id: media_player.kitchen
media_content_id: media-source://media_source/local/doorbell.mp3
media_content_type: musicTTS volume controls can be used with a Media Source TTS URL:
service: media_player.play_media
data:
entity_id: media_player.kitchen
media_content_id: media-source://tts/cloud?message=I am very loud
media_content_type: music
extra:
volume: 80"Standard" TTS service calls can also be used, but the extra parameters cannot be used:
service: tts.cloud_say
data:
entity_id: media_player.front_room
message: "Hello there"A special media_content_id of "CHIME" can be used to test the integration using the built-in sound provided by Sonos. This can be useful for validation if your own URLs are not playing correctly:
service: media_player.play_media
data:
entity_id: media_player.kitchen
media_content_id: CHIME
media_content_type: musicIf you encounter issues playing audio when using this integration, it may be related to one of the following reasons.
If audio playback does not resume after playing a sound, you may have selected the incorrect entity. The integration will create new media_player entities for each Sonos device in your household. You must select these new entities as the target for playback, not the original entities.
Some device models may not support the audioClip feature or will only provide limited support. For example, some older models on S1 firmware may not support this feature at all. A warning message will be logged during startup for each unsupported device. Other speakers (e.g., Play:1 speakers) may support a stripped-down version of the feature which does not overlay the alert audio on top of playing music, but instead will pause/resume the background audio.
A stereo pair will only play back audio on the left speaker and a home theater setup will play from the "primary" speaker. This is because of a limitation in the API which can only target a single speaker device at a time.
When using the play_on_bonded extra key, the integration will attempt to play the audio on all bonded speakers in a "room" by making multiple simultaneous calls. Since playback may not be perfectly synchronized with this method it is not enabled by default.
If serving files from your Home Assistant instance (e.g., from the /www/ config directory or via TTS integrations), the URLs must be resolvable and directly reachable from the Sonos speakers.
To configure TTS integrations to use external URLs, set the base_url configuration option.
Examples:
tts:
- platform: cloud
base_url: 'https://<unique_cloud_id>.ui.nabu.casa'
language: en-US
gender: femaleor
tts:
- platform: google_translate
base_url: 'https://xxxxxx.duckdns.org:8123'Sonos devices have strict security requirements if served media over an SSL/TLS connection. See more details here.