Home

Awesome

Mini Media Player

A minimalistic yet customizable media player card for Home Assistant Lovelace UI.

Inspired by Custom UI: Mini media player and custom-lovelace.

Preview Image

Installation

HACS (recommended)

This card is available in HACS (Home Assistant Community Store).

  1. Install HACS if you don't have it already
  2. Open HACS in Home Assistant
  3. Go to "Frontend" section
  4. Click button with "+" icon
  5. Search for "Mini Media Player"

Manual install

UI mode

  1. Download and copy mini-media-player-bundle.js from the latest release into your config/www directory.
  2. Go to Sidebar -> Settings -> Dashboards -> Menu (top right corner) -> Resources.
  3. Click on + ADD RESOURCE.
  4. Type /local/mini-media-player-bundle.js?v=1.16.9 below URL.
  5. Choose JavaScript Module below Resource Type.
  6. Accept.

YAML mode

  1. Download and copy mini-media-player-bundle.js from the latest release into your config/www directory.
  2. Add a reference to mini-media-player-bundle.js inside your configuration.yaml or through the Home Assistant UI from the resource tab.
lovelace:
  resources:
    - url: /local/mini-media-player-bundle.js?v=1.16.9
      type: module

To update the card to a new version after manual installation, update mini-media-player-bundle.js file from latest release and edit version of the card in your resources. You may need to empty the browsers cache if you have problems loading the updated card.

Using the card

Options

Card options

NameTypeDefaultSinceDescription
typestringrequiredv0.1custom:mini-media-player
entitystringrequiredv0.1An entity_id from an entity within the media_player domain.
namestringoptionalv0.6Override the entities friendly name.
iconstringoptionalv0.1Specify a custom icon from any of the available mdi icons.
icon_imagestringoptionalv1.16.2Override icon with an image url
tap_actionaction objecttruev0.7.0Action on click/tap.
groupbooleanoptionalv0.1Removes paddings, background color and box-shadow.
hideobjectoptionalv1.0.0Manage visible UI elements, see hide object for available options.
artworkstringdefaultv0.4cover to display current artwork in the card background, full-cover to display full artwork, material for alternate artwork display with dynamic colors, none to hide artwork, full-cover-fit for full cover without cropping.
ttsobjectoptionalv1.0.0Show Text-To-Speech input, see TTS object for available options.
sourcestringoptionalv0.7Change source select appearance, icon for just an icon, full for the full source name.
sound_modestringoptionalv1.1.2Change sound mode select appearance, icon for just an icon, full for the full sound mode name.
infostringoptionalv1.0.0Change how the media information is displayed, short to limit media information to one row, scroll to scroll overflowing media info.
volume_statelessbooleanfalsev0.6Swap out the volume slider for volume up & down buttons.
volume_stepnumberoptionalv1.9.0Change the volume step size of the volume buttons and the volume slider (number between 1 - 100)<sup>1</sup>.
max_volumenumberoptionalv0.8.2Specify the max vol limit of the volume slider (number between 1 - 100).
min_volumenumberoptionalv1.1.2Specify the min vol limit of the volume slider (number between 1 - 100).
replace_mutestringoptionalv0.9.8Replace the mute button, available options are play_pause (previously play), stop, play_stop, next.
jump_amountnumber10v0.14.0Configure amount of seconds to skip/rewind for jump buttons.
toggle_powerbooleantruev0.8.9Set to false to change the power button behaviour to media_player.turn_on/media_player.turn_off.
idle_viewobjectoptionalv1.0.0Display a less cluttered view when idle, See Idle object for available options.
backgroundstringoptionalv0.8.6Background image, specify the image url "/local/background-img.png" e.g.
speaker_groupobjectoptionalv1.0.0Speaker group management/multiroom, see Speaker group object for available options.
shortcutsobjectoptionalv1.0.0Media shortcuts in a list or as buttons, see Shortcut object for available options.
scalenumberoptionalv1.5.0UI scale modifier, default is 1.

<a name="option_foot1"><sup>1</sup></a> Only supported on entities with volume_level attribute.

Idle object

NameTypeDefaultDescription
when_idlebooleanoptionalRender the idle view when player state is idle.
when_pausedbooleanoptionalRender the idle view when player state is paused
when_standbybooleanoptionalRender the idle view when player state is standby
afterstringoptionalSpecify a number (minutes) after which the card renders as idle (only supported on platforms exposing media_position_updated_at).

TTS object

NameTypeDefaultDescription
platformstringrequiredSpecify TTS platform, e.g. google_translate or amazon_polly, cloud for Nabu Casa, alexa<sup>1</sup> for "Alexa as Media Player", ga<sup>2</sup><sup>3</sup> for use with Google Assistant Webserver or Assistant Relay, sonos<sup>2</sup> for use with modified sonos_say script, webos<sup>4</sup>, service<sup>5</sup>.
languagestringoptionalThe output language.
entity_idstring/listoptionalThe entity_id of the desired output entity or a list of entity_id's, can also be all to broadcast to all entities or group to target currently grouped speakers.
volumefloatoptionalVolume level of tts output (0 - 1), only supported by platform sonos.
typestringoptionaltts, announce or push, defaults to tts, only supported by platform alexa, more info here.
dataobjectoptionalAny additional data to pass with the notify command.

<a name="tts_foot1"><sup>1</sup></a> Does not support the language option.

<a name="tts_foot2"><sup>2</sup></a> Does not support language & entity_id options.

<a name="tts_foot3"><sup>3</sup></a> Requires a custom notify service named ga_broadcast, see example below.

# configuration.yaml
notify:
  - name: ga_broadcast
    platform: rest
    resource: http://[xxx.x.x.xxx]:5000/broadcast_message

<a name="tts_foot4"><sup>4</sup></a> Requires the card entity name to match the notify service name, if they don't match please specify the notify service name in the entity_id option.

<a name="tts_foot5"><sup>5</sup></a> Specify service & service_data under the data option, specify message_field to use message for the service.

type: custom:mini-media-player
entity: media_player.xiaoai_speaker
tts:
  platform: service
  data:
    service: xiaomi_miot.intelligent_speaker
    service_data:
      execute: true
      silent: true
    message_field: text

Speaker group object

See Speaker group management for example usage.

Supported platforms

NameTypeDefaultDescription
entitieslistrequiredA list containing speaker entities of one of supported platforms, to enable group management of those speakers.
platformstring'sonos'Any supported multiroom platform e.g. sonos, soundtouch, bluesound, see supported platforms above.
sync_volumebooleanoptionalKeep volume Synchronize between grouped speakers.
expandedbooleanoptionalMake the speaker group list expanded by default.
show_group_countbooleantrueHave the number of grouped speakers displayed (if any) in the card name.
iconstringoptionalOverride default group button icon (any mdi icon).
group_mgmt_entitystringoptionalOverride the player entity for the group management (Useful if you use a universal media_player as your entity but still want to use the grouping feature)
supports_masterbooleanoptionalSet to false if your multiroom system does not define one of the media players as master. Defaults to true and has not to be set to false for squeezebox for backward compatibility.

<a name="speaker_foot1"><sup>1</sup></a> All features are not yet supported.

<a name="speaker_foot2"><sup>2</sup></a> Requires custom component for sound devices based on Linkplay chipset, available in HACS.

<a name="speaker_foot3"><sup>3</sup></a> HomeAssistant added join/unjoin services to the media_player. Future official integrations will implement these services (which are slightly different from the ones, which are already supported by this card) instead of implementing them in their own domain.

Speaker entity object

NameTypeDefaultDescription
entity_idstringrequiredThe entity_id for the speaker entity.
namestringrequiredA display name.
volume_offsetnumberoptionalVolume offset (0-100) when used with sync_volume.

Shortcuts object

See card with media shortcuts for example usage.

NameTypeDefaultDescription
listlistoptionalA list of shortcut items to be presented as a list, see shortcut item object.
buttonslistoptionalA list of shortcut items to be presented as buttons.
hide_when_offbooleanfalseHide the shortcuts while the entity is off.
columnsinteger (1-6)2Specify the max number of buttons per row.
column_heightnumberoptionalSpecify the column height in pixels.
labelstringshortcuts...Specify a custom default label for the shortcut dropdown.
attributestringoptionalSpecify any attribute exposed by the media player entity. The attribute value (if exists) is compared with shortcut id's to distinguish selected/active shortcut<sup>1</sup>.
align_textstringoptionalSpecify alignment of button icon/text left, right, center.

<a name="shortcuts_foot1"><sup>1</sup></a> Examples, source for active source or sound_mode for active sound mode.

Shortcut item object

NameTypeDefaultDescription
namestringoptionalA display name.
iconstringoptionalA display icon (any mdi icon).
imagestringoptionalA display image.
coverstringoptionalA cover image (only supported for button shortcuts).
typestringrequiredType of shortcut. A media type: music, tvshow, video, episode, channel, playlist e.g. or an action type: source, sound_mode, script or service.
idstringrequiredThe media identifier. The format of this is component dependent. For example, you can provide URLs to Sonos & Cast but only a playlist ID to iTunes & Spotify. A source/(sound mode) name can also be specified to change source/(sound mode), use together with type source/sound_mode. If type script specify the script name here or service specify the <domain>.<service>.
datalistoptionalExtra service payload<sup>1</sup>.

<a name="shortcut_foot1"><sup>1</sup></a> Only compatible with script & service shortcuts, useful for sending variables to script.

Action object options

NameTypeDefaultOptionsDescription
actionstringmore-infomore-info / navigate / call-service / url / fire-dom-event / noneAction to perform.
entitystringAny entity idOverride default entity of more-info, when action is defined as more-info.
servicestringAny serviceService to call (e.g. media_player.toggle) when action is defined as call-service.
service_dataobjectAny service dataService data to include with the service call (e.g. entity_id: media_player.office).
navigation_pathstringAny pathPath to navigate to (e.g. /lovelace/0/) when action is defined as navigate.
urlstringAny URLURL to open when action is defined as url.
new_tabbooleanfalsetrue / falseOpen URL in new tab when action is defined as url.
hapticstringsuccess, warning, failure, light, medium, heavy, selectionHaptic feedback for the IOS app.

Hide object

NameTypeDefaultDescription
namebooleanfalseThe name.
iconbooleanfalseThe entity icon.
infobooleanfalseThe media information.
powerbooleanfalseThe power button.
sourcebooleanfalseThe source select.
sound_modebooleantrueThe sound_mode select.
group_buttonbooleanfalseThe group button.
controlsbooleanfalseThe media playback controls.
prevbooleanfalseThe "previous" playback control button.
nextbooleanfalseThe "next" playback control button.
play_pausebooleanfalseThe play/pause button in media playback controls.
play_stopbooleantrueThe play/stop button in media playback controls.
jumpbooleantrueThe jump backwards/forwards buttons (entity needs to support progress).
volumebooleanfalseThe volume controls.
volume_levelbooleantrueThe current volume level in percentage.
mutebooleanfalseThe mute button.
progressbooleanfalseThe progress bar.
runtimebooleantrueThe media runtime indicators.
runtime_remainingbooleantrueThe media remaining runtime (requires runtime option to be visible).
artwork_borderbooleantrueThe border of the default artwork picture.
power_statebooleantrueDynamic color of the power button to indicate on/off.
icon_statebooleantrueDynamic color of the entity icon to indicate entity state.
shufflebooleantrueThe shuffle button (only for players with shuffle_set support).
repeatbooleantrueThe repeat button (only for players with repeat_set support).
state_labelbooleanfalseState labels such as Unavailable & Idle.

Theme variables

The following variables are available and can be set in your theme to change the appearence of the card. Can be specified by color name, hexadecimal, rgb, rgba, hsl, hsla, basically anything supported by CSS.

nameDefaultDescription
mini-media-player-base-colorvar(--primary-text-color) & var(--paper-item-icon-color)The color of base text & buttons
mini-media-player-accent-colorvar(--accent-color)The accent color of UI elements
mini-media-player-icon-color--mini-media-player-base-color, var(--paper-item-icon-color, #44739e)The color for icons
mini-media-player-button-colorrgba(255,255,255,0.25)The background color of shortcut and group buttons.
mini-media-player-overlay-colorrgba(0,0,0,0.5)The color of the background overlay
mini-media-player-overlay-color-stop25%The gradient stop of the background overlay
mini-media-player-overlay-base-colorwhiteThe color of base text, icons & buttons while artwork cover is present
mini-media-player-overlay-accent-colorwhiteThe accent color of UI elements while artwork cover is present
mini-media-player-media-cover-info-colorwhiteColor of the media information text while artwork cover is present
mini-media-player-background-opacity1Opacity of the background
mini-media-player-artwork-opacity1Opacity of cover artwork
mini-media-player-progress-height6pxProgressbar height
mini-media-player-scale1Scale of the card
mini-media-player-name-font-weight400Font weight of the entity name

Example usage

Basic card

<img src="https://user-images.githubusercontent.com/457678/52081816-771c1b00-259b-11e9-8c1e-cfd93ac3e66d.png" width="500px" alt="Basic card example" />
type: custom:mini-media-player
entity: media_player.kitchen_speakers

Compact card

Setting either volume and/or controls to true in the hide option object will render the player as a single row.

<img src="https://user-images.githubusercontent.com/457678/53042774-569efc80-3487-11e9-8242-03d388d40c34.png" width="500px" alt="Compact card example" />
type: custom:mini-media-player
entity: media_player.example
icon: mdi:spotify
artwork: cover
hide:
  volume: true
  source: true
  power_state: false

Card with media shortcuts

You can specify media shortcuts through the shortcuts option, either as a list or as buttons or why not both?

<img src="https://user-images.githubusercontent.com/457678/53040712-5e0fd700-3482-11e9-9990-6ca13b871f50.png" width="500px" alt="Card with media shortcuts example">
- entity: media_player.spotify
  type: custom:mini-media-player
  artwork: cover
  source: icon
  hide:
    volume: true
  shortcuts:
    columns: 4 # Max buttons per row
    buttons:
      # Start predefined playlist
      - icon: mdi:cat
        type: playlist
        id: spotify:user:XXXXXXX:playlist:37i9dQZF1DZ06evO2O09Hg # Where XXXXXXX is your User ID
      # Change the source to bathroom
      - icon: mdi:dog
        type: source
        id: Bathroom
      # Trigger script
      - icon: mdi:dog
        type: script
        id: script.script_name
      # Trigger custom service
      - name: Crooners Playlist
        type: service
        id: spotcast.start
        data:
          entity_id: media_player.googlehome1234
          uri: spotify:playlist:37i9dQZF1DX9XiAcF7t1s5

      ... # etc.

Tip: If you don't have Sonos, but want just a bit more control over playlists and so, a simple solution is to use the type: service-option, to trigger thespotcast.start-service.

Remember to add the required data, for spotcast to work. Also, kindly note that the spotcast custom component is required, for this to work. It's available in HACS.

Grouped cards

Set the group option to true when nesting mini media player cards inside other cards that already have margins/paddings.

<img src="https://user-images.githubusercontent.com/457678/52081831-800cec80-259b-11e9-9b35-63b23805c879.png" width="500px" alt="Grouped cards example" />
type: entities
entities:
  - type: custom:mini-media-player
    entity: media_player.multiroom_player
    group: true
    source: icon
    info: short
    hide:
      volume: true
      power: true
  - type: custom:mini-media-player
    entity: media_player.kitchen_speakers
    group: true
    hide:
      controls: true
  - type: custom:mini-media-player
    entity: media_player.bathroom_speakers
    group: true
    hide:
      controls: true
  - type: custom:mini-media-player
    entity: media_player.bedroom_speakers
    group: true
    hide:
      controls: true
  - type: custom:mini-media-player
    entity: media_player.patio_speakers
    group: true
    hide:
      controls: true

Stacked cards

By using vertical and horizontal stacks, you can achieve many different setups.

<img src="https://user-images.githubusercontent.com/457678/52081830-800cec80-259b-11e9-9a77-0e8585c3f71c.png" width="500px" alt="Stacked cards example" />
- type: horizontal-stack
  cards:
    - entity: media_player.tv_livingroom
      type: custom:mini-media-player
      info: short
      artwork: cover
      hide:
        mute: true
        icon: true
        power_state: false
    - entity: media_player.tv_bedroom
      type: custom:mini-media-player
      info: short
      artwork: cover
      hide:
        mute: true
        icon: true
        power_state: false
- type: horizontal-stack
  cards:
    - entity: media_player.cc_patio
      type: custom:mini-media-player
      hide:
        icon: true
    - entity: media_player.cc_kitchen
      type: custom:mini-media-player
      hide:
        icon: true
    - entity: media_player.cc_bath
      type: custom:mini-media-player
      hide:
        icon: true

Speaker group management

Specify all your speaker entities in a list under the option speaker_group -> entities. They obviously need to be of the same platform.

<img src="https://user-images.githubusercontent.com/457678/52181170-53511300-27ef-11e9-9d54-aa9c84a96168.gif" width="500px" alt="sonos group management example">
type: custom:mini-media-player
entity: media_player.sonos_office
hide:
  power: true
  icon: true
  source: true
speaker_group:
  platform: sonos
  show_group_count: true
  entities:
    - entity_id: media_player.sonos_office
      name: Sonos Office
    - entity_id: media_player.sonos_livingroom
      name: Sonos Livingroom
    - entity_id: media_player.sonos_kitchen
      name: Sonos Kitchen
    - entity_id: media_player.sonos_bathroom
      name: Sonos Bathroom
    - entity_id: media_player.sonos_bedroom
      name: Sonos Bedroom

If you are planning to use the speaker_group option in several cards, creating a separate yaml file for the list is highly recommended, this will result in a less cluttered ui-lovelace.yaml and also make the list easier to manage and maintain. You then simply reference the file containing the list using entities: !include filename.yaml for every occurrence of entities in your ui-lovelace.yaml.

This is however only possible when you have lovelace mode set to yaml in your HA configuration, see Lovelace YAML mode for more info.

Development

If you plan to contribute back to this repo, please fork & create the PR against the dev branch.

Clone this repository into your config/www folder using git.

$ git clone https://github.com/kalkih/mini-media-player.git

Add a reference to the card in your ui-lovelace.yaml.

resources:
  - url: /local/mini-media-player/dist/mini-media-player-bundle.js
    type: module

Instructions

Requires nodejs & npm

  1. Move into the mini-media-player repo, checkout the dev branch & install dependencies.
$ cd mini-media-player && git checkout dev && npm install
  1. Make changes to the source

  2. Build the source by running

$ npm run build
  1. Refresh the browser to see changes

    Make sure cache is cleared or disabled

  2. (Optional) Watch the source and automatically rebuild on save

$ npm run watch

The new mini-media-player-bundle.js will be build and ready inside /dist.

Getting errors?

Make sure you have javascript_version: latest in your configuration.yaml under frontend:.

Make sure you have the latest version of mini-media-player-bundle.js.

If you have issues after updating the card, try clearing your browsers cache or restart Home Assistant.

If you are getting "Custom element doesn't exist: mini-media-player" or running older browsers try replacing type: module with type: js in your resource reference, like below.

resources:
  - url: ...
    type: js

Inspiration

License

This project is under the MIT license.