DOCSEARCHbyAlgolia
Submit Docs

Mediocre Media Player Cards

repository·main·Indexed 19 days ago

https://github.com/antontanderup/mediocre-hass-media-player-cards

A collection of custom Home Assistant Lovelace cards for advanced media player control. Features include the Mediocre Media Player Card, Massive Media Player Card, Multi Media Player Card, and Chip Media Player Group Card. Supports speaker grouping, custom actions, and deep integration with Music Assistant and Lyrion Media Server (LMS) via the lyrion_cli integration, including a specialized LyrionMediaBrowser for navigation and global search.

Tokens
16.2K
Snippets
36
Records
68
Agent score
63%

What's inside mediocre-hass-media-player-cards

  1. Overview of available Media Player Cards

    main

    The repository provides several specialized cards for Home Assistant:

    • Mediocre Media Player Card: A standard-sized card for a single entity. Supports grouping, custom actions, and optional Music Assistant integration.
    • Mediocre Massive Media Player Card: A full-sized, feature-rich card for a single media player. Includes all features of the standard card plus multiple display modes.
    • Mediocre Multi Media Player Card: Allows controlling and viewing multiple media players simultaneously. Ideal for dashboards with multiple speakers or grouped devices.
    • Mediocre Chip Media Player Group Card: A compact, chip-style card designed for quickly grouping or ungrouping speakers. Often used as a companion to other media player cards.

  2. Overview of LyrionMediaBrowser

    main

    The LyrionMediaBrowser is a media browser component designed for Logitech Media Server (LMS) or Lyrion Music Server. It communicates with the server via the lyrion_cli Home Assistant integration.

    Core Architecture

    • LyrionMediaBrowser.tsx: The root component handling the navigation bar, breadcrumbs, search input, and the virtual list.
    • useLyrionMediaBrowserData.ts: The central state hook managing navigation history, item enrichment, row grouping, and playback actions.
    • useLyrionBrowse.ts: A hook that fetches single LMS browse/query results and transforms them into LyrionBrowserItem[].
    • useLyrionGlobalSearch.ts: Handles home-screen search by firing four parallel queries (artists, albums, tracks, and playlists).
    • useHassMessagePromise: The underlying mechanism that calls the lyrion_cli.query Home Assistant service.

  3. Overview of Mediocre Media Player Cards

    main
    The mediocre-hass-media-player-cards project provides custom Home Assistant Lovelace cards designed for media player entities. It includes advanced features like group cards and massive player cards. The project is built using TypeScript and Preact (using React-compatible syntax) and is designed for modularity and reusability within the Home Assistant ecosystem.

  5. Understand the LyrionMediaBrowser Navigation Model

    main

    Navigation is managed through a history state array of BrowserHistoryEntry objects. The first entry (history[0]) is always a synthetic HOME_ENTRY sentinel. The visible breadcrumbs represent history.slice(1) (the navHistory).

    History Entry Structure

    Each entry contains:

    • id: LMS item ID or category name (e.g., "artists").
    • title: Display name for breadcrumbs.
    • command: The LMS CLI command (e.g., "albums", "titles").
    • parameters: Extra parameters (e.g., ["role_id:ALBUMARTIST"]).
    • type: Item type ("category", "artist", "album", "track", "genre", "playlist", "app").
    • filter: The active search/filter string.

    Navigation Actions

    • Click category: Replaces everything after the home sentinel with a new category entry.
    • Click expandable item: Appends a new entry; the next command is derived from the type (e.g., genre $\rightarrow$ artists, artist $\rightarrow$ albums, album/playlist $\rightarrow$ titles).
    • Click app: Appends an entry where the app's id is also its CLI command.
    • Back: Removes the last entry from history.
    • Breadcrumb click: Slices the history to the clicked index.
    • Home: Resets history to [HOME_ENTRY] and clears input.

  7. Integrate Lyrion (LMS) Queue Management

    main

    To enable queue transfer and management for Lyrion (LMS), use the following:

    • lms_entity_id: The LMS entity ID. This adds queue management when paired with lyrion_cli.
    • options.use_experimental_lms_media_browser: Set to true to replace the built-in media browser with an experimental lyrion_cli-based browser. This includes global search and app access (e.g., Spotty, Qobuz). This requires lms_entity_id and lyrion_cli to be configured.

  8. Integrate Music Assistant (MA) Search and Favorites

    main

    To enable search and queue management features when using Music Assistant, provide the following:

    • ma_entity_id: The Music Assistant entity ID. This enables search and queue management when paired with hass_queue.
    • ma_favorite_button_entity_id: The Music Assistant favorite button entity. This adds a heart-plus button to mark the current song as a favorite.
    • search: An array of objects containing entity_id, name, and media_types to enable the search UI via the search_media action.

  9. Component development patterns

    main

    When developing or extending components in this project, follow these established patterns:

    • Export Style: Always use named exports; do not use default exports.
    • Functional Components: Use functional components with Preact hooks (useContext, useState, useCallback, useMemo, etc.).
    • Context Usage: Access shared state and configuration via context providers like CardContext or PlayerContext.
    • Styling: Use CSS-in-JS via @emotion/react's css function. Define a styles object at the top of the file and apply it using the css prop.
    • Responsiveness: Use container queries instead of regular media queries to ensure components respond correctly to the size of their container within the Lovelace UI.
    • Service Calls: Do not call Home Assistant services directly; use abstracted utility functions such as getHass().callService(...).
    • Imports: Use path aliases for utilities and types (e.g., @utils and @types).

  10. How to use Universal Media Player with Mediocre Media Player Cards

    main

    Universal Media Player (UMP) in Home Assistant allows you to control multiple media players as a single entity, but it lacks native support for grouping players. You can bridge this gap by using the mediocre-media-player-card with the speaker_group configuration. This allows you to use a single UMP entity for playback control while simultaneously managing speaker grouping via a separate media player entity.

    To implement this, you must configure the card to point to your UMP entity and define a speaker_group that contains the main grouping entity and the list of speakers to be included in that group.

    type: "custom:mediocre-media-player-card"
entity_id: media_player.living_room_universal
speaker_group:
  entity_id: media_player.living_room
  entities:
    - media_player.living_room
    - media_player.kitchen
    - media_player.bedroom

  11. Browse Modes in LyrionMediaBrowser

    main

    The component operates in four distinct browsing modes:

    1. Home Screen

    Displayed when navHistory.length === 0 and no filter is active. It shows:

    • Categories: A grid of static CATEGORIES.
    • New Music: Recent albums via albums 0 100 sort:new tags:alj.
    • Favorites: Favorites via favorites items 0 100 want_url:1.
    • Apps: Apps via apps 0 100.

    2. Category / Nested Browsing

    Uses useLyrionBrowse to fetch data. It uses a BrowseContext (extracted by walking the history stack) to build parameters:

    • Root category: Uses the category command directly with specific tags (e.g., tags:alj for albums).
    • Nested navigation: Injects ancestor IDs (genre, artist, album, playlist) as _id: filter parameters.
    • Playlists: Uses playlists tracks <playlist_id>.
    • Apps/Radio: Uses <app_cmd> items with item_id:.

    3. Global Search

    Triggered on the home screen via useLyrionGlobalSearch. It runs four parallel queries:

    • Artists: artists with tags:a
    • Albums: albums with tags:alj
    • Tracks: titles with tags:altj
    • Playlists: playlists (no tags)

    4. In-category Search

    Appends search:<term> to the LMS query. It uses a 350ms debounce. Search is disabled for Favorites and for Apps until the first browse result returns an appSearchItemId.

  12. Customize card appearance with CSS variables

    main
    The Mediocre Media Player Card allows for visual customization using specific CSS variables. If these variables are not explicitly defined, the card automatically falls back to standard Home Assistant theme variables. When applying custom styles, it is recommended to test them in both light and dark modes to ensure compatibility with your Home Assistant theme.