Add search possibility to Media Source

[mib1185]

Context

We already added search capabilities to media players which supports browsing in #677 / home-assistant/core#140321. There are many integrations (eq. Google Photos, Immich, Radio Browser, Synology DSM, ...) providing only the media browsing part, as they implement a Media Source. We should also allow these medias to be browsed and searched.

Proposal

1. async_search_media on the MediaSource base class

We add a search method to the MediaSource base class. Because media sources are stateless and receive the item to act on, the signature takes the resolved item plus the query (vs. the MediaPlayer.async_search_media(query) variant), similar to the Media search implementation. We don't support searching the aggregate root (over all integrations at once).

2. Signaling searchability → reuse can_search

Instead of adding a new is_searchable property or a MediaSourceEntityFeature enum, we reuse the existing per-item can_search flag on BrowseMedia/BrowseMediaSource. Sources set can_search=True on the browsable items where search makes sense (e.g. directories), so the frontend shows the search bar contextually rather than globally, allowing integrations to limit search to certain sub-types.

3. Reuse the dataclasses from media_player

Rather than duplicating or moving them to a shared helper, we import the existing dataclasses/consts from media_player — SearchMedia, SearchMediaQuery, MediaClass, ATTR_MEDIA_SEARCH_QUERY, ATTR_MEDIA_FILTER_CLASSES. This keeps a single source of truth and keeps custom components working.

4. Websocket endpoint media_source/search_media

We adopt the media_player/search_media pattern as a dedicated media_source/search_media command (mirroring media_source/browse_media):

5. Allow integrations to expose available media classes for search filtering

Problem. media_player/search_media already accepts media_filter_classes (and similarly the media_browser search would) to narrow results by MediaClass. But the frontend currently has no way to know which classes a given source can actually return, so it cannot render a meaningful filter UI — it would have to show all ~20 MediaClass values (most irrelevant) or none. A photo source should offer image/video; a music source music/album/artist/playlist/track. Add a small companion capability so integrations can advertise the classes available for filtering at a given browse context. Add a property search_supported_classes to the BrowseMedia so the frontend can display the avialable filter classes, contextually aware to the current folder.

[timmo001]

It's been spoken about before, we need a vector search functionality in core, allowing fast search via potentially a seperate database. This applies to mostly internal data, external apis can surface search themselves (plex/jellyfin for example).

However, I don't see a reason that properties and functions like these could not be added now and apis can surface the search themselves. We can add a searchable database later for certain cases in the media search. Radio browser is an example for this, however there might be a simpler search api we could add before this.

So long as the endpoints/subscriptions are available for frontend, we can add this in.

Also curious on the current state of properties, it seems like these might be the start of an implementation, that need a refactor.

---

This could only be per integration, so it would mean frontend could only show search inside of the integration itself, which makes sense to start with anyway, I don't think a quick search for media sources could actually be done until everything supports it, which is not possible in all integrations, especially those with limited data access like external filesystems or have no search api available from the provider.

[balloob]

I think for now we should just focus on leveraging existing search functionality offered by the API providing the media source

[balloob]

Instead of add is_searchable property to the MediaSource, we should add a search method to it. It works exactly like the media player method, and we can forward calls to it when searching a media player.

[mib1185]

we should add a search method to it.

yeah, I forgot to mention that in the description - sure, we need a search method in the MediaSource. I'll update the description. The is_searchable property is for the frontend, so it can consider to show or hide any search bars (or so) when the media source doesn't support search

[mib1185]

Seems to be already implemented with home-assistant/core#175485 😬

[emontnemery]

The merged implementation PR is not matching this proposal.

The proposal says there will be a way to signal support for search, but it's not clear how this signalling should be implemented. We’ll revert the implementation PR for now, then we can make a decision either on revised version of this proposal which clearly specifies how the signalling should be implemented.

[zweckj]

So there are a couple of things that need a direction:

• should search be context aware (respect the item a user is currently in): in that case we should use the currently unused can_search property to allow integrations to define in which container a search is even possible
• if it should not be context aware, remove can_search and use an entity feature instead
• how should search be handled from the frontend: Is it an interactive search (searching without the press of enter after 500ms), do we have concerns overloading the backend API with this
• should we add an endpoint which allows integrations to give available MediaClasses for searching to the frontend (let the integration define which one it even supports) - suggestion: yes
• if we don't make it context aware/non-interactive: We should probably add a quicker search to the frontend in some way, that just filters down a longer result set based on name/class. Since the result sets are maximum of 100 items, I believe we could do that entirely in the frontend, or are there reasons not do that?
• if we have two searches (search & filter) how do we make it clear for the user which one is which?

[zweckj]

This proposal was discussed and approved in the Home Assistant Architecture meeting on 23.07.2026.

[mib1185]

• Add search_media_classes to media browser core#177146