Add Sonos favorites notes (#22642)

Co-authored-by: Franck Nijhof <git@frenck.dev>

source/_integrations/sonos.markdown

@@ -40,6 +40,7 @@ Speaker-level controls are exposed as `number` or `switch` entities. Additionall
 
 ### Sensors
 
+- **Each Sonos system**: Sonos Favorites
 - **Devices with battery**: Battery level, Power state
 - **Home theater devices**: Audio Input Format
 - **Voice-enabled devices**: Microphone Enabled
@@ -64,6 +65,41 @@ The Sonos integration adds one `switch` for each alarm set in the Sonos app. The
 
 The microphone can only be enabled/disabled from physical buttons on the Sonos device and cannot be controlled from Home Assistant. A `binary_sensor` reports its current state.
 
+### Sonos Favorites support notes
+
+The favorites sensor provides the names and `media_content_id` values for each of the favorites saved to My Sonos in the native Sonos app. This sensor is intended for users that need to access the favorites in a custom template. For most users, accessing favorites by using the Media Browser functionality and "Play media" script/automation action is recommended.
+
+If using the provided `media_content_id` with the `media_player.play_media` service, the `media_content_type` must be set to "favorite_item_id".
+
+Example templates:
+
+{% raw %}
+
+```yaml
+# Get all favorite names as a list (old behavior)
+{{ state_attr("sensor.sonos_favorites", "items").values() | list }}
+
+# Pick a specific favorite name by position
+{{ (state_attr("sensor.sonos_favorites", "items").values() | list)[3] }}
+
+# Pick a random item's `media_content_id`
+{{ state_attr("sensor.sonos_favorites", "items") | list | random }}
+
+# Loop through and grab name & media_content_id
+{% for media_id, name in state_attr("sensor.sonos_favorites", "items").items() %}
+  {{ name, media_id }}
+{% endfor %}
+```
+
+{% endraw %}
+
+<div class='note'>
+
+The Sonos favorites sensor (`sensor.sonos_favorites`) is disabled by default. It can be found and enabled from the entities associated with the Sonos integration on your {% my integrations %} page.
+  
+</div>
+
+
 ## 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.