From f36b8656d83efdf12bfd15bdff1168ed6658f554 Mon Sep 17 00:00:00 2001 From: jjlawren Date: Thu, 17 Jun 2021 13:28:01 -0500 Subject: [PATCH] Describe Sonos media_player.play_media support (#18202) * Describe Sonos media_player.play_media support * Move description out of services, add examples * Apply suggestions from code review Co-authored-by: Franck Nijhof * Add note on account requirement for services * Add second Spotify example to clarify URI/URL Co-authored-by: Franck Nijhof --- source/_integrations/sonos.markdown | 55 +++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/source/_integrations/sonos.markdown b/source/_integrations/sonos.markdown index e05946d9185..fc4e5b3135a 100644 --- a/source/_integrations/sonos.markdown +++ b/source/_integrations/sonos.markdown @@ -40,6 +40,61 @@ The battery sensors rely on working change events or updates will be delayed. S1 The Sonos integration adds one `switch` for each alarm set in the Sonos app. The alarm switches are detected, deleted and assigned automatically and come with several attributes that help to monitor Sonos alarms. +## Playing media + +Sonos accepts a variety of `media_content_id` formats in the `media_player.play_media` service, but most commonly as URIs. For example, both Spotify and Tidal share links can be provided as-is. Playback of [music hosted on a Plex server](/integrations/plex#sonos-playback) is possible. Direct HTTP/HTTPS links to local or remote media files can also be used if the Sonos device can reach the URI directly, but specific media encoding support may vary. + +Music services which require an account (e.g., Spotify) must first be configured using the Sonos app. + +An optional `enqueue` argument can be added to the service call. If `true`, the media will be appended to the end of the playback queue. If not provided or `false` then the queue will be replaced. + +### Examples: + +This is an example service call that plays an audio file from a web server on the local network (like the Home Assistant built-in webserver): + +```yaml +service: media_player.play_media +target: + entity_id: media_player.sonos +data: + media_content_type: "music" + media_content_id: "http://192.168.1.50:8123/local/sound_files/doorbell-front.mp3" +``` + +Sonos can also play music or playlists from Spotify. Both Spotify URIs and URLs can be used directly. An example service call using a playlist URI: + +```yaml +service: media_player.play_media +target: + entity_id: media_player.sonos +data: + media_content_type: "playlist" + media_content_id: "spotify:playlist:abcdefghij0123456789XY" + enqueue: true +``` + +An example service call using a Spotify URL: + +```yaml +service: media_player.play_media +target: + entity_id: media_player.sonos +data: + media_content_type: "music" + media_content_id: "https://open.spotify.com/album/abcdefghij0123456789YZ" +``` + +Run a [Plex Media Server](/integrations/plex#sonos-playback) in your home? The Sonos integration can work with that as well. This example plays music directly from your Plex server: + +```yaml +service: media_player.play_media +target: + entity_id: media_player.sonos +data: + media_content_type: "music" + media_content_id: 'plex://{ "library_name": "Music", "artist_name": "M83", "album_name": "Hurry Up, We're Dreaming" }' +``` + ## Services The Sonos integration makes various custom services available.