From d4a98012a3454fe895e257102dced961b0f6657c Mon Sep 17 00:00:00 2001
From: Pete Sage <76050312+PeteRager@users.noreply.github.com>
Date: Mon, 13 May 2024 09:05:18 -0400
Subject: [PATCH] Sonos - updates to play media content ids (#32717)

* Update sonos.markdown

* Tiny tweak to fix the CI

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
---
 source/_integrations/sonos.markdown | 68 +++++++++++++++++++++++++++--
 1 file changed, 65 insertions(+), 3 deletions(-)

diff --git a/source/_integrations/sonos.markdown b/source/_integrations/sonos.markdown
index 20fb050e83a..ae676ba3cd8 100644
--- a/source/_integrations/sonos.markdown
+++ b/source/_integrations/sonos.markdown
@@ -71,7 +71,7 @@ The favorites sensor provides the names and `media_content_id` values for each o
 
 When calling the `media_player.play_media` service, the `media_content_type` must be set to "favorite_item_id" and the `media_content_id` must be set to just the key portion of the favorite item. 
 
-Example service call:
+Example service call using the item id:
 
 ```yaml
 service: media_player.play_media
@@ -82,6 +82,17 @@ data:
   media_content_id: "FV:2/31"
 ```
 
+Example using the Sonos playlist name:
+
+```yaml
+service: media_player.play_media
+target:
+  entity_id: media_player.sonos_speaker1
+data:
+  media_content_type: playlist
+  media_content_id: stevie_wonder
+```
+
 Example templates:
 
 {% raw %}
@@ -119,7 +130,7 @@ Music services which require an account (e.g., Spotify) must first be configured
 
 Playing TTS (text-to-speech) or audio files as alerts (e.g., a doorbell or alarm) is possible by setting the `announce` argument to `true`. Using `announce` will play the provided media URL as an overlay, gently lowering the current music volume and automatically restoring to the original level when finished. An optional `volume` argument can also be provided in the `extra` dictionary to play the alert at a specific volume level. Note that older Sonos hardware or legacy firmware versions ("S1") may not fully support these features. Additionally, see [Network Requirements](#network-requirements) for use in restricted networking environments.
 
-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.
+An optional `enqueue` argument can be added to the service call. If `replace` or not provided then the queue will be replaced and the item will be replaced. If `add` the item will be appended to the queue. If `next` the item will be added into the queue to play next. If `play`, the item will be added into the queue and played immediately.
 
 ### Examples:
 
@@ -186,6 +197,57 @@ data:
     plex://{ "library_name": "Music", "artist_name": "M83", "album_name": "Hurry Up, We're Dreaming" }
 ```
 
+#### Sonos Music Library
+
+If you have configured a Sonos music library; you can play music from it.
+
+Play all albums by the Beatles.
+
+```yaml
+service: media_player.play_media
+target:
+  entity_id: media_player.sonos
+data:
+  media_content_type: album
+  media_content_id: A:ALBUMARTIST/Beatles
+```
+
+Play a specific album:
+
+```yaml
+service: media_player.play_media
+target:
+  entity_id: media_player.sonos
+data:
+  media_content_type: album
+  media_content_id: A:ALBUM/The Wall
+  enqueue: replace
+```
+
+Or add a specific album by a specific artist to the queue.  This is useful in case you have multiple albums with the same name.
+
+```yaml
+service: media_player.play_media
+target:
+  entity_id: media_player.sonos      
+data:
+  media_content_type: album
+  media_content_id: A:ALBUMARTIST/Neil Young/Greatest Hits
+  enqueue: add
+```
+
+Play all albums by a composer.
+
+```yaml
+service: media_player.play_media
+target:
+  entity_id: media_player.porch
+data:
+  media_content_type: composer
+  media_content_id: A:COMPOSER/Carlos Santana
+  enqueue: play
+```
+
 ## Services
 
 The Sonos integration makes various custom services available in addition to the [standard media player services](/integrations/media_player/#services).
@@ -346,4 +408,4 @@ The Sonos speakers will attempt to connect back to Home Assistant to deliver cha
 sonos:
   media_player:
     advertise_addr: 192.0.2.1
-```
+```
\ No newline at end of file