Media Player Entity

• Features
  • Attributes
  • States
  • Device Classes
  • Options
• Integration API
  • Commands
  • Simple Commands
    • Command Name Patterns
  • Events
    • Media types
    • 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, media browsing and searching.

🧑‍💻 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.

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 options. 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: -/_.:+#*°@%()?
  • 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

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 types

The media_type attribute specifies the media being played:

• MUSIC
• RADIO
• TVSHOW
• MOVIE
• VIDEO

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

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.
• 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
• Define media types
• Playlist handling
• Media browsing
• Searching