Document media player changes (#1352)

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

blog/2022-05-31-media-player-updates.md

@@ -0,0 +1,11 @@
+---
+author: Paulus Schoutsen
+authorURL: https://twitter.com/balloob
+authorImageURL: /img/profile/paulus.jpg
+authorTwitter: balloob
+title: "Media Player updates: enqueue changes, announce added"
+---
+
+Starting with Home Assistant 2022.6, the media player integration has received two updates to the `media_player.play_media` service. The `enqueue` attribute has been changed to a string in [PR #72406](https://github.com/home-assistant/core/pull/72406) and a new `announce` boolean attribute was added in [PR #72566](https://github.com/home-assistant/core/pull/72566).
+
+See the updated [media player play_media documentation](/docs/core/entity/media-player/#play-media) for more information.

docs/core/entity/media-player.md

@@ -55,6 +55,42 @@ and are combined using the bitwise or (`|`) operator.
 
 ## Methods
 
+### Play Media
+
+Tells the media player to play media. Implement it using the following:
+
+```python
+class MyMediaPlayer(MediaPlayerEntity):
+
+    def play_media(
+        self,
+        media_type: str,
+        media_id: str,
+        enqueue: MediaPlayerEnqueue | None = None,
+        announce: bool | None = None, **kwargs: Any
+    ) -> None:
+        """Play a piece of media."""
+
+    async def async_play_media(
+        self,
+        media_type: str,
+        media_id: str,
+        enqueue: MediaPlayerEnqueue | None = None,
+        announce: bool | None = None, **kwargs: Any
+    ) -> None:
+        """Play a piece of media."""
+
+```
+
+The `enqueue` attribute is a string enum `MediaPlayerEnqueue`:
+
+ - `add`: add given media item to end of the queue
+ - `next`: play the given media item next, keep queue
+ - `play`: play the given media item now, keep queue
+ - `replace`: play the given media item now, clear queue
+
+When the `announce` boolean attribute is set to `true`, the media player should try to pause the current music, announce the media to the user and then resume the music.
+
 ### Browse Media
 
 If the media player supports browsing media, it should implement the following method:
@@ -99,7 +135,11 @@ class MyMediaPlayer(MediaPlayerEntity):
         )
 
     async def async_play_media(
-        self, media_type: str, media_id: str, **kwargs: Any
+        self,
+        media_type: str,
+        media_id: str,
+        enqueue: MediaPlayerEnqueue | None = None,
+        announce: bool | None = None, **kwargs: Any
     ) -> None:
         """Play a piece of media."""
         if media_source.is_media_source_id(media_id):