Revise media source documentation for search support

[mib1185]

Updated the media source documentation to reflect changes in the data types and added examples for enabling search support based on specific paths.

Proposed change

This tries to improve and clarify how to advertise search support.

Type of change

• Document existing features within Home Assistant
• Document new or changing features for which there is an existing pull request elsewhere
• Spelling or grammatical corrections, or rewording for improved clarity
• Editing or restructuring documentation guidelines
• Changes to the backend of this documentation
• Remove stale or deprecated documentation

Checklist

• I have read and followed the documentation guidelines.
• I have verified that my changes render correctly in the documentation.

Additional information

• This PR fixes or closes issue: fixes #
• Link to relevant existing code or pull request:

Summary by CodeRabbit

• Documentation
  • Clarified the media-source search behavior and updated the expected type for search results.
  • Updated guidance for when the media browser search bar appears—now based on can_search=True on the root media source returned by async_browse_media().
  • Refreshed the example to show how to derive the root can_search value from the current media item identifier (for example, via an is_searchable(...)-style check for directories).

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 06468d0b-8d8c-42ea-97b7-21d9876e9444

📥 Commits

Reviewing files that changed from the base of the PR and between 5b78810 and eb10ca1.

📒 Files selected for processing (1)

• docs/core/platform/media_source.md

✅ Files skipped from review due to trivial changes (1)

• docs/core/platform/media_source.md

---

📝 Walkthrough

Walkthrough

Documentation for media-source searching is updated: SearchMedia.result is now documented as Sequence[BrowseMedia], and search-bar visibility is described as depending on can_search=True on the root BrowseMediaSource.

Changes

Media source search documentation

Layer / File(s)	Summary
Search result type and support guidance docs/core/platform/media_source.md	Documents SearchMedia.result as Sequence[BrowseMedia] and rewrites the search-support guidance to place can_search=True on the root BrowseMediaSource, with the example deriving that value from MediaSourceItem.identifier.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• home-assistant/developers.home-assistant#3228: Updates the same media-source search documentation area and related can_search guidance.

Suggested reviewers: balloob

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: updating media source documentation for search support.
Description check	✅ Passed	The description follows the template and covers the change, type, checklist, and additional info, though some placeholders remain unfilled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch improve-media-source-search-support

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Updates the Media Source platform documentation to align search-related type hints with current Home Assistant models and to clarify how integrations should advertise search support in the media browser.

Changes:

• Updated SearchMedia.result type documentation to Sequence[BrowseMedia].
• Revised the “Advertising search support” guidance and expanded the examples, including conditional search enablement based on the current MediaSourceItem.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[zweckj]

Suggested change

	identifier=None,
	identifier=item.identifier,

is probably the more correct default for most cases

[mib1185]

AFAIK the identifier should be None for the root element and only the child elements should get their correct identifier set.

https://developers.home-assistant.io/docs/core/platform/media_source#browsemediasource

Parameter	Type	Description
identifier	str | None	Item-specific identifier. Use None for root items.

it's also in all other examples above, that the root element always has identifier=None

[zweckj]

That's why I am saying not using one is probably the better default as None only works for root specifically and could be a common pitfall if the frontend is not aware of the current position in the directory structure

[mib1185]

I think I got it now - the returned BrowseMediaSource is the current visible container, whereas the childs are those are displayed? So the BrowseMediaSource is not the root of the integrations media source.

[zweckj]

Exactly