Add search capabilities to media player

blog/2025-04-01-search-media-play.md

@@ -0,0 +1,25 @@
+---
+author: Josef Zweck
+authorURL: https://github.com/zweckj
+authorImageURL: https://avatars.githubusercontent.com/u/24647999?v=4
+title: "Searching in media players"
+---
+
+Media players can now allow users to search through the media, by adding `MediaEntityFeature.SEARCH_MEDIA` and implementing `async_search_media`.
+
+The users can filter the search result by a search query and a list of `MediaClasses` that the returned results should have.
+
+Inside of `async_search_media` the developer is responsible for querying the requested results from their serving API and returning it as a list of `BrowseMedia` as part of the `SearchMedia` result.
+
+ ```python
+ class MyMediaPlayer(MediaPlayerEntity):
+
+     async def async_search_media(
+         self,
+         query: SearchMediaQuery,
+     ) -> SearchMedia:
+         """Search the media player."""
+         # search for the reqested media on your library client.
+         result = await my_client.search(query=query.search_query)
+         return SearchMedia(result=result)
+ ```

docs/core/entity/media-player.md

@@ -67,6 +67,7 @@ and are combined using the bitwise or (`|`) operator.
 | `PLAY_MEDIA`        | Entity allows playing media sources.                               |
 | `PREVIOUS_TRACK`    | Entity allows returning back to a previous media track.            |
 | `REPEAT_SET`        | Entity allows setting repeat.                                      |
+| `SEARCH_MEDIA`      | Entity allows searching for media.                                 |
 | `SEEK`              | Entity allows seeking position during playback of media.           |
 | `SELECT_SOUND_MODE` | Entity allows selecting a sound mode.                              |
 | `SELECT_SOURCE`     | Entity allows selecting a source/input.                            |
@@ -192,6 +193,25 @@ class MyMediaPlayer(MediaPlayerEntity):
         await self._media_player.play_url(media_id)
 ```
 
+### Search media
+
+If the media player supports searching media, it should implement the following method:
+
+```python
+class MyMediaPlayer(MediaPlayerEntity):
+
+    async def async_search_media(
+        self,
+        query: SearchMediaQuery,
+    ) -> SearchMedia:
+        """Search the media player."""
+        # search for the requested media on your library client.
+        result = await my_client.search(query=query.search_query)
+        return SearchMedia(result=result)
+```
+
+A user can also further filter the search results by only requesting a list of `MediaClass`.
+
 ### Select sound mode
 
 Optional. Switch the sound mode of the media player.