Add native Android media controls for HA media_player entities

[FletcherD]

Summary

I wanted to be able to control a media player entity natively on Android without having to open the app or navigate to a widget. So this feature exposes a Home Assistant media_player entity as native Android Media Controls (described here) in the notification shade, the same UI used by other media players on Android.
The media controls show the currently playing track info and play position with album art. Prev/next track, play/pause and seek controls work and are forwarded to the media_player entity (if the entity supports them).
A new "Media controls" setting is added under "Companion app" to choose which media_player entity to expose in the media controls, if any. One entity at a time can be selected.
Unit tests are added to test playback state mapping, state flow, settings and everything else I could think of.

Checklist

• New or updated tests have been added to cover the changes following the testing guidelines.
• The code follows the project's code style and best_practices.
• The changes have been thoroughly tested, and edge cases have been considered.
• Changes are backward compatible whenever feasible. Any breaking changes are documented in the changelog for users and/or in the code for developers depending on the relevance.

Screenshots

Link to pull request in documentation repositories

User Documentation PR: home-assistant/companion.home-assistant#1304

[home-assistant]

Hi @FletcherD

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

[home-assistant]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

[Copilot]

Pull request overview

Adds a new feature that exposes a selected Home Assistant media_player entity as native Android media controls (MediaSession) and provides a settings UI to configure which entity is exposed.

Changes:

• Introduces MediaControlRepository + state model and preference storage for the configured server/entity
• Adds a MediaSessionService (HaMediaSessionService) + remote Player adapter to bridge Android transport controls to HA service calls
• Adds settings entry + Compose settings screen, plus unit/Robolectric tests and changelog entry

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
common/src/test/kotlin/io/homeassistant/companion/android/common/data/mediacontrol/MediaControlRepositoryImplTest.kt	Unit tests for repository state observation and mapping
common/src/main/res/values/strings.xml	Adds user-facing strings for media controls settings
common/src/main/kotlin/io/homeassistant/companion/android/common/data/prefs/PrefsRepositoryImpl.kt	Persists/clears configured media control server/entity preferences
common/src/main/kotlin/io/homeassistant/companion/android/common/data/prefs/PrefsRepository.kt	Adds preference APIs for media control configuration
common/src/main/kotlin/io/homeassistant/companion/android/common/data/mediacontrol/MediaControlState.kt	Defines media control state + playback state model
common/src/main/kotlin/io/homeassistant/companion/android/common/data/mediacontrol/MediaControlRepositoryImpl.kt	Observes entity state via WebSocket and maps to MediaControlState
common/src/main/kotlin/io/homeassistant/companion/android/common/data/mediacontrol/MediaControlRepository.kt	Repository contract for state/config management
common/src/main/kotlin/io/homeassistant/companion/android/common/data/mediacontrol/MediaControlModule.kt	Hilt binding for the repository implementation
common/src/main/kotlin/io/homeassistant/companion/android/common/data/integration/Entity.kt	Adds media_player supported feature bitmasks and media metadata helpers
automotive/src/main/AndroidManifest.xml	Declares MediaSessionService + FGS media playback permission
automotive/lint-baseline.xml	Updates baseline (including new Compose lint entries)
app/src/test/kotlin/io/homeassistant/companion/android/settings/mediacontrol/MediaControlSettingsViewModelTest.kt	Unit tests for settings ViewModel interactions
app/src/test/kotlin/io/homeassistant/companion/android/mediacontrol/HaRemoteMediaPlayerTest.kt	Robolectric tests for player state/commands mapping
app/src/main/res/xml/preferences.xml	Adds settings category + entry point for media controls
app/src/main/res/xml/changelog_master.xml	Adds changelog entry for the new feature
app/src/main/res/drawable/ic_play_circle_outline.xml	Adds icon for the settings entry
app/src/main/kotlin/io/homeassistant/companion/android/settings/mediacontrol/views/MediaControlSettingsView.kt	Compose UI for selecting server/entity and saving/clearing
app/src/main/kotlin/io/homeassistant/companion/android/settings/mediacontrol/MediaControlSettingsViewModel.kt	Loads servers/entities/registries and starts/stops the service on save/clear
app/src/main/kotlin/io/homeassistant/companion/android/settings/mediacontrol/MediaControlSettingsFragment.kt	Hosts the Compose settings screen in a Fragment
app/src/main/kotlin/io/homeassistant/companion/android/settings/SettingsFragment.kt	Wires the new preference entry to the settings fragment navigation
app/src/main/kotlin/io/homeassistant/companion/android/mediacontrol/HaRemoteMediaPlayer.kt	SimpleBasePlayer adapter translating Android commands to callbacks
app/src/main/kotlin/io/homeassistant/companion/android/mediacontrol/HaMediaSessionService.kt	MediaSessionService observing HA state, loading artwork, and calling HA actions
app/src/main/AndroidManifest.xml	Declares MediaSessionService + FGS media playback permission
app/lint-baseline.xml	Updates baseline (including new Compose lint entries)

[github-advanced-security]

ktlint found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated 2 comments.

[FletcherD]

Closing to recreate with clean history.