DOCSEARCHbyAlgolia
Submit Docs

Mini Media Player

repository·master·Indexed 23 days ago

https://github.com/kalkih/mini-media-player

A minimalistic and highly customizable media player card for the Home Assistant Lovelace UI. Version 1.16.12 provides advanced controls for media entities, including custom shortcuts for scripts and services, text-to-speech (TTS) input, and multiroom speaker group management for platforms such as Sonos, Soundtouch, and Squeezebox. It supports extensive UI customization via theme variables, artwork styles, and the ability to hide specific elements for compact layouts.

Tokens
5.2K
Snippets
8
Records
27
Agent score
83%

What's inside mini-media-player

  1. Overview of Mini Media Player features

    master

    Mini Media Player is a minimalistic and highly customizable media player card designed for the Home Assistant Lovelace UI. It provides advanced control over media entities, including playback, volume, seeking, and source selection. Key capabilities include:

    • Customization: Hide/display specific items, custom backgrounds, theme variables, and multiple artwork styles.
    • Advanced Controls: Custom shortcuts (to trigger scripts, services, or play media), text-to-speech input, and shuffle support.
    • Multiroom Management: Support for grouping and managing speakers from systems like Sonos, Soundtouch, Squeezebox, Bluesound, Musiccast, and Linkplay.
    • UI Layouts: Responsive design with options for compact views, grouped cards, and stacked cards.

  2. Manage speaker groups and multiroom

    master

    The speaker_group option enables group management for supported platforms (e.g., sonos, soundtouch, musiccast, squeezebox, bluesound, snapcast, linkplay, media_player, heos).

    Requirements:

    • The entities list must contain speaker_entity objects.
    • The card's primary entity must be the coordinator/master speaker of the group.
    • All speakers in the list must belong to the same platform.

    Speaker Entity Object:

    • entity_id (required): The entity ID of the speaker.
    • name (required): A display name.
    • volume_offset (optional): Volume offset (0-100) used with sync_volume.
    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

  3. Hide UI elements in Mini Media Player

    master

    Use the hide object to manage the visibility of various UI elements. This is useful for creating compact cards or specialized views. Setting volume: true and/or controls: true in the hide object will render the player as a single row.

    type: custom:mini-media-player
entity: media_player.example
artwork: cover
hide:
  volume: true
  source: true
  power_state: false

  4. Set up Mini Media Player for development

    master

    To contribute to the project, fork the repository and create a PR against the dev branch. To develop locally, clone the repository into your Home Assistant config/www folder and register the resource in your ui-lovelace.yaml.

    Resource Registration: Add the following to your ui-lovelace.yaml:

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

    Build Workflow:

    1. Navigate to the repo, checkout the dev branch, and install dependencies:
    $ cd mini-media-player && git checkout dev && npm install
    1. Make your changes.
    2. Build the bundle:
    $ npm run build
    1. (Optional) Use watch mode to rebuild automatically on save:
    $ npm run watch

    Note: Ensure your browser cache is cleared or disabled to see changes. The built bundle is located in the /dist directory.

    $ cd mini-media-player && git checkout dev && npm install
$ npm run build
$ npm run watch

  5. Configure the Mini Media Player card

    master

    The custom:mini-media-player card is used to control media players in Home Assistant. It requires a type of custom:mini-media-player and an entity from the media_player domain. You can customize its appearance using options like artwork (e.g., cover, full-cover, material, none), icon, name, and scale.

    type: custom:mini-media-player
entity: media_player.kitchen_speakers

  6. Configure media shortcuts

    master

    The shortcuts option allows you to add media shortcuts as a list or as buttons. Shortcuts can be of several types: music, tvshow, video, episode, channel, playlist, source, sound_mode, script, or service.

    For script and service types, you must provide an id (the script name or <domain>.<service>) and can optionally provide a data payload.

    - entity: media_player.spotify
  type: custom:mini-media-player
  artwork: cover
  source: icon
  hide:
    volume: true
  shortcuts:
    columns: 4
    buttons:
      - icon: mdi:cat
        type: playlist
        id: spotify:user:XXXXXXX:playlist:37i9dQZF1DZ06evO2O09Hg
      - icon: mdi:dog
        type: source
        id: Bathroom
      - icon: mdi:dog
        type: script
        id: script.script_name
      - name: Crooners Playlist
        type: service
        id: spotcast.start
        data:
          entity_id: media_player.googlehome1234
          uri: spotify:playlist:37i9dQZF1DX9XiAcF7t1s5

  7. Install Mini Media Player manually (UI mode)

    master

    If you are not using HACS, you can install the card manually using the Home Assistant UI:

    1. Download mini-media-player-bundle.js from the latest release.
    2. Copy the file into your Home Assistant config/www directory.
    3. In the Home Assistant sidebar, go to Settings -> Dashboards.
    4. Click the Menu (top right corner) and select Resources.
    5. Click + ADD RESOURCE.
    6. Enter /local/mini-media-player-bundle.js?v=1.16.12 in the URL field.
    7. Select JavaScript Module as the Resource Type.
    8. Click Accept.

  8. Install Mini Media Player manually (YAML mode)

    master

    To install the card via your configuration.yaml file:

    1. Download mini-media-player-bundle.js from the latest release.
    2. Copy the file into your Home Assistant config/www directory.
    3. Add the following resource configuration to your configuration.yaml under the lovelace section:

    Note: When updating the card, you must replace the file in config/www and update the version query parameter (e.g., ?v=1.16.12) in your configuration to ensure the browser loads the new version. You may need to clear your browser cache if updates do not appear.

    lovelace:
  resources:
    - url: /local/mini-media-player-bundle.js?v=1.16.12
      type: module

  9. Install Mini Media Player via HACS

    master

    The recommended way to install Mini Media Player is through the Home Assistant Community Store (HACS).

    1. Ensure HACS is installed in your Home Assistant instance.
    2. Open the HACS interface.
    3. Navigate to the Frontend section.
    4. Click the + icon to add a new resource.
    5. Search for "Mini Media Player" and select it to install.

  10. Use the Mini Media Player Lovelace card

    master

    The mini-media-player is a custom Home Assistant Lovelace card designed for minimalistic and highly customizable media control. It is registered as a custom element <mini-media-player> and can be used in your Home Assistant dashboard. It supports features like speaker grouping, adaptive colors from artwork, and various layout modes (e.g., collapse, material artwork).

    To use it, add the card to your dashboard and provide a configuration object. The card automatically handles state updates via the hass object provided by Home Assistant.

  11. Customize card appearance with Theme Variables

    master

    You can override the card's appearance by setting the following CSS variables in your Home Assistant theme. Values can be color names, hex, rgb, rgba, hsl, or hsla.

    NameDefaultDescription
    mini-media-player-base-colorvar(--primary-text-color) & var(--paper-item-icon-color)Base text & buttons
    mini-media-player-accent-colorvar(--accent-color)Accent color of UI elements
    mini-media-player-icon-color--mini-media-player-base-color, var(--paper-item-icon-color, #44739e)Color for icons
    mini-media-player-button-colorrgba(255,255,255,0.25)Background color of shortcut and group buttons
    mini-media-player-overlay-colorrgba(0,0,0,0.5)Background overlay color
    mini-media-player-overlay-color-stop25%Gradient stop of the background overlay
    mini-media-player-overlay-base-colorwhiteBase text, icons & buttons color when artwork cover is present
    mini-media-player-overlay-accent-colorwhiteAccent color of UI elements when artwork cover is present
    mini-media-player-media-cover-info-colorwhiteMedia information text color when 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

  12. How Mini Media Player merges configuration options

    master

    The card uses a hierarchical merging strategy for its configuration. When you provide a configuration object, it is merged with internal defaults.

    Key behaviors include:

    • hide: Merges your provided hide object with DEFAULT_HIDE values.
    • speaker_group: Merges your sonos and speaker_group configuration blocks into a single speaker_group object.
    • shortcuts: Merges your shortcuts with the default LABEL_SHORTCUT.
    • volume: max_volume defaults to 100 and min_volume defaults to 0 if not specified.
    • Automatic Layout Adjustments: The card automatically calculates collapse and flow states based on your hide settings. For example, if you hide controls or volume, the card sets collapse: true.