Media player entity

A media player entity controls something that plays media: a smart speaker, a TV, a streaming stick, an AV receiver, or a projector. It reports what is playing, with artwork and position, and takes commands like play, pause, volume, source, and play this URL. It is one of the richest entity types in Home Assistant, but you only implement what your device can do: the supported features decide which actions and controls exist.

Inherit from MediaPlayerEntity, imported from homeassistant.components.media_player. For how the frontend shows a media player, see the media player more-info view.

These properties are specific to media player entities. The generic properties every entity has are on the entity class. All of them default to None, except where the table says otherwise.

The frontend moves the position bar forward by itself, based on media_position and media_position_updated_at. So only update the two when the position really jumps, like after a seek or a new track, not every second. Updating them every second only fills the database.

When the state is off, Home Assistant leaves out the media attributes, the volume, source, sound mode, shuffle, and repeat attributes, and the entity picture. The group_members attribute stays, for players that support grouping.

Combine the flags of MediaPlayerEntityFeature with the bitwise or (|) operator. Home Assistant only offers an action when the entity has the flag for it.

The device class tells Home Assistant, and voice assistants that sync with it, what kind of device this is. Use the MediaPlayerDeviceClass enum.

The media_player.play_media action calls play_media with the media type, the media ID, and some options in kwargs:

• enqueue: a MediaPlayerEnqueue that says what to do with the queue. add adds the media to the end of the queue, next plays it after the current item, play plays it now and keeps the queue, and replace plays it now and clears the queue. The action editor only offers it for players with MEDIA_ENQUEUE, but Home Assistant does not filter it out, so ignore it if you do not support it.
• announce: True for an announcement, like a doorbell sound or a text-to-speech message. Pause what is playing, play the announcement, and resume. The action editor only offers it for players with MEDIA_ANNOUNCE.
• extra: a dictionary with extra options from the action call. Always present, and empty by default.

An action call can have enqueue or announce, never both.

media_type is usually a MediaType value. If your integration handles media that does not fit any of them, it is fine to use your integration domain as the type.

With BROWSE_MEDIA, implement async_browse_media. It gets a media_content_type and a media_content_id, both None for the root, and returns a BrowseMedia object: a tree of items, each with a title, a media class (MediaClass), an ID, whether it can be played or expanded, and a thumbnail. Raise BrowseError for an ID you do not know.

The media source integration lets any integration offer media: local files, text-to-speech, radio stations, cameras. If your player can play a URL, add those sources to your browser for free. Pass the browse call on to media_source.async_browse_media, or add its root to your own tree. When you play a media source ID, resolve it to a URL first with media_source.async_resolve_media, and run that URL through async_process_play_media_url, which turns a relative URL into one your device can reach.

If your thumbnails are only reachable from the local network, proxy them through Home Assistant, so they also work in the companion app away from home. Set the thumbnail of a BrowseMedia item to self.get_browse_image_url(media_content_type, media_content_id, media_image_id). When the browser loads it, Home Assistant calls your async_get_browse_image. Fetch the image there with self._async_fetch_image(url), and return a tuple of the content and the content type.

Only proxy when the request comes from outside the network: is_local_request(hass) from homeassistant.helpers.network tells you. The artwork of what is playing now goes through async_get_media_image, which has its own cache: you only need to set media_image_url.

With SEARCH_MEDIA, implement async_search_media. It gets a SearchMediaQuery with a search_query, and optionally a media_content_type, a media_content_id to search in, and media_filter_classes, a list of MediaClass values to limit the results. Return a SearchMedia with the matching BrowseMedia items in result.

Each method has a sync and an async variant. Implement one of them. The async variants start with async_, like async_media_play.

Some methods have a default you can override:

• toggle: turns the player on when it is off, and off otherwise.
• media_play_pause: pauses when the state is playing, and plays otherwise.
• volume_up and volume_down: change volume_level by volume_step through set_volume_level, when the player has VOLUME_SET. Implement them yourself if your device has its own volume buttons.

Return a MediaPlayerState from state.

Many players cannot be controlled while they are in standby. If Home Assistant can still turn the device on another way, like Wake-on-LAN or a power command over a different connection, show it as off. If there is no way to turn it on from Home Assistant, mark the entity unavailable. The entity unavailable rule of the quality scale has the details.

A network speaker that plays, pauses, sets the volume, and plays URLs, including media sources.

from typing import Any

from homeassistant.components import media_source
from homeassistant.components.media_player import (
    BrowseMedia,
    MediaPlayerDeviceClass,
    MediaPlayerEntity,
    MediaPlayerEntityFeature,
    MediaPlayerState,
    MediaType,
    async_process_play_media_url,
)


class MySpeaker(MediaPlayerEntity):
    """A network speaker."""

    _attr_has_entity_name = True
    _attr_name = None
    _attr_device_class = MediaPlayerDeviceClass.SPEAKER
    _attr_supported_features = (
        MediaPlayerEntityFeature.PLAY
        | MediaPlayerEntityFeature.PAUSE
        | MediaPlayerEntityFeature.VOLUME_SET
        | MediaPlayerEntityFeature.PLAY_MEDIA
        | MediaPlayerEntityFeature.BROWSE_MEDIA
    )

    def __init__(self, speaker: MySpeakerClient) -> None:
        """Initialize the speaker."""
        self._speaker = speaker
        self._attr_unique_id = speaker.serial

    @property
    def state(self) -> MediaPlayerState:
        """Return the state of the speaker."""
        if self._speaker.is_playing:
            return MediaPlayerState.PLAYING
        return MediaPlayerState.IDLE

    @property
    def volume_level(self) -> float:
        """Return the volume, from 0 to 1."""
        return self._speaker.volume / 100

    async def async_media_play(self) -> None:
        """Resume playback."""
        await self._speaker.play()

    async def async_media_pause(self) -> None:
        """Pause playback."""
        await self._speaker.pause()

    async def async_set_volume_level(self, volume: float) -> None:
        """Set the volume."""
        await self._speaker.set_volume(round(volume * 100))

    async def async_browse_media(
        self,
        media_content_type: MediaType | str | None = None,
        media_content_id: str | None = None,
    ) -> BrowseMedia:
        """Browse the audio of media sources."""
        return await media_source.async_browse_media(
            self.hass,
            media_content_id,
            content_filter=lambda item: item.media_content_type.startswith(
                "audio/"
            ),
        )

    async def async_play_media(
        self, media_type: MediaType | str, media_id: str, **kwargs: Any
    ) -> None:
        """Play a URL or a media source."""
        if media_source.is_media_source_id(media_id):
            play_item = await media_source.async_resolve_media(
                self.hass, media_id, self.entity_id
            )
            media_id = play_item.url

        url = async_process_play_media_url(self.hass, media_id)
        await self._speaker.play_url(url)