From f77d0672d094495ee793ebcd26d48d8423e32cfc Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Tue, 31 May 2022 14:36:25 -0700 Subject: [PATCH] Document media player changes (#1352) Co-authored-by: Martin Hjelmare --- blog/2022-05-31-media-player-updates.md | 11 +++++++ docs/core/entity/media-player.md | 42 ++++++++++++++++++++++++- 2 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 blog/2022-05-31-media-player-updates.md diff --git a/blog/2022-05-31-media-player-updates.md b/blog/2022-05-31-media-player-updates.md new file mode 100644 index 00000000..d7d181e7 --- /dev/null +++ b/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. diff --git a/docs/core/entity/media-player.md b/docs/core/entity/media-player.md index 668d5f0c..12b34898 100644 --- a/docs/core/entity/media-player.md +++ b/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):