Media Player Entity

• Features
  • Attributes
  • States
  • Device Classes
  • Options
• Integration API
  • Commands
  • Simple Commands
    • Command Name Patterns
  • Media Browsing
    • Browse Response
    • Home Assistant Integration Example
  • Media Searching
    • Search Response
    • Example
  • Media Playback
    • Media Play Action
  • Events
    • Media Content Types
    • Media Classes
    • Media images
  • Command examples
    • on
    • play_pause
    • volume
    • seek
    • repeat
    • shuffle
    • select_sound_mode
    • Custom simple command
  • Event examples
    • State change event
• Open issues and missing features

A media player entity controls playback of media on a device. This could be an online music streaming service, a TV, a stereo, or a video player.

Features

Media-player features define the capabilities of the controlled device. For example, the dpad feature will enable the four directional commands and the enter command. Furthermore, certain features control the appearance and functionality of the media-player UI on the Remote Two.

• R: readable
  • ✅ Feature has a readable attribute to retrieve the current or available values.
  • ❌ Feature value(s) cannot be read.
• W: writeable
  • ✅ Feature has one or multiple commands to trigger an action or set a value.
  • ❌ No corresponding command(s), only the current value(s) of the feature can be read.

🚧 Planned features are: playlist handling.

🧑‍💻 Integration driver developers:

• If certain features or commands are missing for your device, they can be defined with “simple commands”.
• If a feature doesn’t fully match your device, for example, it only has a record function but no my_recordings or live functions, then the desired command(s) should also be defined as a “simple command”.
  • For the command name use the corresponding cmd_id in uppercase to keep any command related automations.
    (This would be RECORD for the record-only feature example).

Attributes

Entity attributes are enabled by features and hold the current value of a feature or provide available options. Multiple features can act on the same attribute.

States

The entity state attribute holds the following values:

See also common entity states.

Device Classes

Optional: the media player can be classified what kind of device it represents. This can be used by the UI to represent the media player with a different icon, behaviour etc.

Options

Optional features of the media-player entity.

stable_id_support

The numeric stable_id_support value is a bit field that defines which stable IDs are supported by the integration:

• Bit 0: browse always returns stable ids.
• Bit 1: browse supports stable ids with the stable_ids parameter.
• Bit 2: search always returns stable ids.
• Bit 3: search returns stable ids with the stable_ids parameter.

Using the stable_ids parameter for browse and search might incur a runtime cost and should only be used where stable ids are persisted, like in the play_media command.

Integration API

Commands

The integration driver has to implement a handler for the entity_command message to process the following command requests in msg_data.cmd_id.

Simple Commands

Additional commands can be enabled with the simple_commands option. A device exposing a media-player entity can support all additional device commands, not covered with the standard features, as so-called “simple commands.” These commands are comparable with the infrared remote-entity commands, where keys trigger an action on the device:

• The command is fully defined by its name and doesn’t have any further arguments or related attributes.
• Command names must be upper case and may not contain spaces.
  • The upper case restriction makes them distinguishable from the pre-defined feature commands.
  • Only a subset of the 7-bit ASCII printable characters are allowed: -/_.:+#*°@%()?
  • The maximum length is 20 characters.
  • Command name regex: ^[A-Z0-9\/_.:+#*°@%()?-]{1,20}$
• 🚧 Simple commands cannot be translated yet. In the web-configurator they show up as defined.

Command Name Patterns

Even though command names can be freely defined with the allowed characters, the following prefixes should be used. This allows better integration into Remote Two, like default UI mappings and grouping of similar commands.

• INPUT_: source inputs, e.g. INPUT_AUX1, INPUT_TV, INPUT_RADIO
• APP_: applications, e.g. APP_MY_TV_STREAMING, APP_INTERNET
• MODE_: mode changing functions, e.g. MODE_16/9, MODE_SURROUND, MODE_FOOTBALL
• MENU_: additional menus, e.g. MENU_SMART_HOME, MENU_QUICK
• DIGIT_: additional input digits besides the pre-defined numpad digits, e.g. DIGIT_10, DIGIT_10+
• ZONE_: multi-room functions, e.g. ZONE_A, ZONE_MULTIROOM

Media Browsing

Media browsing uses a dedicated WebSocket message and is not part of the standard media-player entity commands.

The media_id and media_type parameters are optional and can be used to restrict browsing to a specific media item or content type. Both fields can be returned in the browse response on the root item and on every child item to describe where the item lives in the provider’s hierarchy and how it can be addressed later. For example, for playback or further browsing.

Integrations must ensure that any media_id returned by a given entity is stable and uniquely identifies the item within that entity. This ensures that it can be reused in subsequent play_media, browse_media and search_media calls. Integrations may use either one of the pre-defined semantic content types (see Media Content Types) or provider-specific URIs for media_type, as long as values are stable and reused consistently.

Certain media providers may not support stable identifiers, but the integration might be able to use a workaround generating stable identifiers on the client side. The stable_ids parameter is a hint that the client really requires stable media identifiers in the returned media_id and media_type fields, because the identifier won’t be used right now to play a media item but sometime in the future.
Roon is such an example, which generates new media keys for every new browse or search request. Use cases like
“select an identifier of my favorite playlist, so I can still play it next month” aren’t possible with changing identifiers. As a workaround, the integration driver can return a path structure (Library/Playlists/Favorite Songs) or another sort of identifier that can be used to identify or resolve the item in the future.

Important: When using media_id and media_type values in further calls, they must match the values returned in the previous media_browse response exactly. If an integration returns an empty string ("") as value, that exact empty string will be sent back on later calls and does not mean “no value.”

A field is only omitted from a request if it was not present in the response at all or if it was explicitly set to null in the browse response.

The optional paging object can be used to retrieve a specific page of media items and to limit result size:

• limit: Maximum number of items to return per page. Default is 10.
• page: 1-based page index. Default is 1.

Integrations may return fewer than limit items on the last page; clients must not assume the number of items equals limit.

Browse Response

The msg_data object returned by the media_browse command contains the following fields:

BrowseMediaItem object:

The items array is only present if the current item is a container and contains the same BrowseMediaItem objects. Child items may not contain further child items (only one level of nesting is supported).

• If a flag is omitted on an item, the default is false.
• Integrations should at least provide can_browse for items that can be used as media_id in follow-up browse_media calls.
• For leaf items that can be used with play_media, integrations should set can_play: true.
• Items where all three flags are false should NOT be returned.
  Otherwise, the item will have no associated command in the user interface.
• The media_class and media_type fields use the same semantics and values as documented in the Media Classes and Media Content Types sections.
• The thumbnail field can contain artwork for the current item:
  • An icon URI to use a provided icon with the following prefix: icon://uc:, for example, icon://uc:music.
  • A URL to download the media artwork.
  • A base64 encoded PNG or JPG image.
  • The preferred size is 480x480 pixels, either in JPG or PNG format.
  • Please avoid using encoded images whenever possible. Payloads should be as small as possible.
  • If no thumbnail is provided, a default icon will be used based on media_class.

The pagination object in the response should contain:

• count: Total number of items in the container (not just in the current page). If unknown, this field is not returned.
• limit: The effective page size used for this response.
• page: The 1-based page index used for this response.

Please refer to the Integration API specification for the exact definitions of all data structures.

Home Assistant Integration Example with Spotify Media Player

Example request to browse media at the root level:

{
  "kind": "req",
  "id": 50,
  "msg": "browse_media",
  "msg_data": {
    "entity_id": "media_player.spotify"
  }
}

Example response:

{
  "kind": "resp",
  "req_id": 50,
  "msg": "media_browse",
  "code": 200,
  "msg_data": {
    "media": {
      "title": "Media Library",
      "can_browse": true,
      "media_class": "directory",
      "media_id": "library",
      "media_type": "spotify://library",
      "items": [
        {
          "can_browse": true,
          "media_class": "directory",
          "media_id": "current_user_playlists",
          "media_type": "spotify://current_user_playlists",
          "title": "Playlists"
        },
        {
          "can_browse": true,
          "media_class": "directory",
          "media_id": "current_user_followed_artists",
          "media_type": "spotify://current_user_followed_artists",
          "title": "Artists"
        },
        {
          "can_browse": true,
          "media_class": "directory",
          "media_id": "current_user_saved_albums",
          "media_type": "spotify://current_user_saved_albums",
          "title": "Albums"
        },
        {
          "can_browse": true,
          "media_class": "directory",
          "media_id": "current_user_saved_tracks",
          "media_type": "spotify://current_user_saved_tracks",
          "title": "Liked songs"
        },
        {
          "can_browse": true,
          "media_class": "directory",
          "media_id": "current_user_saved_shows",
          "media_type": "spotify://current_user_saved_shows",
          "title": "Podcasts"
        },
        {
          "can_browse": true,
          "media_class": "directory",
          "media_id": "current_user_recently_played",
          "media_type": "spotify://current_user_recently_played",
          "title": "Recently played"
        },
        {
          "can_browse": true,
          "media_class": "directory",
          "media_id": "current_user_top_artists",
          "media_type": "spotify://current_user_top_artists",
          "title": "Top Artists"
        },
        {
          "can_browse": true,
          "media_class": "directory",
          "media_id": "current_user_top_tracks",
          "media_type": "spotify://current_user_top_tracks",
          "title": "Top Tracks"
        },
        {
          "can_browse": true,
          "media_class": "directory",
          "media_id": "new_releases",
          "media_type": "spotify://new_releases",
          "title": "New Releases"
        }
      ]
    },
    "pagination": {
      "count": 9,
      "limit": 9,
      "page": 1
    }
  }
}

A returned item can be used to continue browsing, if "can_browse": true is set.

For example, to continue browsing the returned “Playlists” directory, send a new request with the returned media_id and media_type values of that item:

{
  "kind": "req",
  "id": 51,
  "msg": "browse_media",
  "msg_data": {
    "entity_id": "media_player.spotify",
    "media_id": "current_user_playlists",
    "media_type": "spotify://current_user_playlists",
    "paging": {
      "limit": 10,
      "page": 1
    }
  }
}

Media Searching

🚧 This is a development feature and subject to change. There is no UI support yet.

Media searching uses a dedicated WebSocket message and is not part of the standard media-player entity commands.

Note: The filter object is not yet formally defined in the Integration-API. The fields below are examples of possible filters and are not required.

The media_id and media_type parameters behave the same as in browse_media: they can be used to restrict the search to a specific container or content type, and integrations should propagate and reuse the values consistently. Empty strings must be preserved and echoed back as-is. Only omit a field if it was not returned or was explicitly null.

• The optional filter.media_classes filter may only contain media classes that are supported by the integration.
  • Supported media classes must be specified in the search_media_classes attribute by the integration.
  • Only well-known Media Classes should be used without any custom media classes.
• See Media Browsing for a description of the stable_ids parameter.
• 🚧 The filter.artist and filter.album fields are examples of possible future filters and are not yet formally defined.
• The optional paging object can be used to retrieve a specific page of media items and to limit result size.

Search Response

The msg_data object returned by the media_search command contains the following fields:

The SearchMediaItem object is identical to the BrowseMediaItem object, except it does not contain the items field:

Example

{
  "kind": "req",
  "id": 124,
  "msg": "search_media",
  "msg_data": {
    "entity_id": "media-1",
    "query": "live",
    "filter": {
      "media_classes": [ "artist", "album"],
      "artist": "Tricky",
      "album": "Pieces"
    },
    "paging": {
      "limit": 5,
      "page": 1
    }
  }
}

Media Playback

Starting a media playback is an optional feature and uses a standard entity_command request with the play_media command identifier.

The media_id and media_type parameters must be the exact same values as returned by browse_media or search_media. The integration can support other identifiers for directly playing a specific media item in activity sequences or UI commands.

{
  "kind": "req",
  "id": 125,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "play_media",
    "params": {
      "media_id": "track-456",
      "media_type": "track",
      "action": "PLAY_NOW"
    }
  }
}

Media Play Action

The play_media_action feature allows integrations to define the behavior of the play_media command in the optional action parameter. Supported values are defined in the MediaPlayAction enum in the Integration-API: The following actions are pre-defined in the Integration-API and are supported in the UI:

• PLAY_NOW: Start playback immediately.
• PLAY_NEXT: Add to the queue after the current item.
• ADD_TO_QUEUE: Add to the end of the queue.

The PLAY_NOW action is the default if no action is specified.

Supported actions must be specified in the play_media_action attribute by the integration.

Integrations may support additional actions that are not defined in the MediaPlayAction enum, for example, a “radio mode.” Please note that custom actions might not be exposed in the UI.

Events

The entity_change event must be emitted by the integration driver if the state or an attribute of the media player changes.

The following attributes are supported:

At least one attribute must be specified in the entity_change message. If the entity state and another attribute changed at the same time, for example if a new track starts playing, they may both be included in the same message. It’s also valid to always send every attribute.

Media Content Types

The media content type is for playback/content semantics. It represents the type of the media content to play or that is currently playing.

• Content type of current playing media.
• The play_media command uses media_type to tell the integration what semantic category of content is being requested.
• In media search, the search query includes an optional media_type used to constrain which content type to search in.

The following media content types are pre-defined:

• album
• app
• apps
• artist
• channel
• channels
• composer
• episode
• game
• genre
• image
• movie
• music
• playlist
• podcast
• radio
• season
• track
• tv_show
• url
• video

The integration may return other values, but the UI will most likely handle them as an “unknown media.”

Media Classes

The media class is for browser/structure semantics. It represents how a media item should be presented and organized in the media browser hierarchy.

Media classes are used by the frontend and media browser infrastructure to:

• Decide how to render items (folder vs leaf item, icons, metadata fields).
• Decide whether an item is expandable or directly playable.
• Filter results in search or browse operations.

The following media classes are pre-defined:

• album
• app
• artist
• channel
• composer
• directory
• episode
• game
• genre
• image
• movie
• music
• playlist
• podcast
• radio
• season
• track
• tv_show
• url
• video

The integration may return other values, but the UI will most likely treat them as generic media without custom icons.

Media images

• Supported image formats: jpg and png.
• The album art image can either be provided as a single image or as three matching image sizes.
  • Images will automatically be resized to the required sizes.
    Either from the single image in media_image_url or from the individual sizes.
  • Images too large in pixel or file size will be rejected due to resource constraints on the remote.
  • Images can be provided as a URL or as base64 encoded data.
• Preferred image sizes in pixel:
  • Large, for full screen album art: 420 x 420
  • Medium: 100 x 100
  • Small, for thumbnails: 60 x 60

Command examples

on

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "on"
  }
}

play_pause

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "play_pause"
  }
}

volume

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "volume",
    "params": {
      "volume": 40
    }
  }
}

seek

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "seek",
    "params": {
      "media_position": 180
    }
  }
}

repeat

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "repeat",
    "params": {
      "repeat": "ALL"
    }
  }
}

shuffle

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "shuffle",
    "params": {
      "shuffle": true
    }
  }
}

select_sound_mode

Specify a sound mode value contained in the sound_mode_list attribute array.

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "select_sound_mode",
    "params": {
      "mode": "MOVIE"
    }
  }
}

Custom simple command

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "THUMBS_UP"
  }
}

Event examples

State change event

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "attributes": {
      "state": "PLAYING",
      "media_duration": 245,
      "media_position": 1,
      "media_position_updated_at": "2025-03-18T07:30:00.000Z",
      "media_title": "Some title",
      "media_artist": "My artist",
      "media_album": "Best of",
      "media_image_url_large": "http://192.168.1.100/player/current/album_l.png",
      "media_image_url_medium": "http://192.168.1.100/player/current/album_m.png",
      "media_image_url_small": "http://192.168.1.100/player/current/album_s.png"
    }
  }
}

Open issues and missing features

• Define album art image limits
• Playlist handling