Media Card

Features

• Two cards: a full Media Card (custom:media-card) and a compact Media Mini Card (custom:media-mini-card)
• Artwork with a blurred artwork background behind the whole card (show_background), title, artist, album, and "Track 3 of 12" when the player tells its queue position (Sonos)
• Progress bar with elapsed and total time, moving every second while playing; click it to seek, or focus it and use the arrow keys (10 s), Home and End
• Controls: power, shuffle, previous, play / pause (or stop), next, repeat (off → all → one), each one only when the player supports it
• Volume slider with the whole percentage, mute, or - / + buttons for a player that only steps its volume
• Several players (players): the full card stacks a block per player (artwork, track, progress, controls, volume), the mini card lists them one per row; only_playing keeps only the ones that are playing (see Several players)
• Rooms: every speaker the shown player can be grouped with (same integration, grouping supported) or the players of the entities option, each with its state, its track, its own volume and mute; a click on a room's name shows that player in the card
• Speaker groups: a link button per room joins it to the group or takes it out (media_player.join / unjoin); Ungroup all asks first, in a popup at the top of the card; the subtitle tells who the player plays with
• Source and sound mode chips (inputs of a receiver, Sonos favorites and line-in, Spotify Connect devices…)
• Queue of Music Assistant players: current and next track with their artwork, and the queue length; a click on the next track skips to it
• Favorites: your own list (any play_media content: radio, playlist, Music Assistant URI, Alexa content…) and the Sonos favorites, played on the shown player
• Jellyfin: an episode shows its series and episode ("Harbor Tales · S2E5"), a film says so, the client app is in the subtitle, and idle sessions stay out of the way (hide_idle_sessions)
• Alexa Media Player (Echo): "Last called" badge, next alarm, timer and reminder, a do-not-disturb button, and Alexa speaker groups shown as groups
• Apple TV and HomePod: the app playing in the subtitle, the episode (Series · S1E4), the apps as sources, an optional remote (show_remote); a HomePod is a speaker
• Animated: the record slides out of the sleeve and turns while playing, the equalizer bounces, glows while paused, a ring turns while buffering, the drawn speaker beats, the TV screen glows, the playing rooms of a group ring (see Animations); prefers-reduced-motion stops them
• Drawn speaker, TV and receiver pictures for a player without artwork, following its device_class, and device pictures by model for Echo speakers and displays, HomePods and Apple TV boxes (see Drawn pictures)
• Header icon of the kind of player (speaker, speaker group, TV, receiver) in a tinted circle colored by its state, and a state chip on the title line
• Collapsible sections (source, queue and favorites folded by default); a click elsewhere on the page folds them back
• Detail button on the mini card (top right): it switches the mini card to the full card's content and back; a click anywhere outside the card brings the compact view back
• Buttons disabled while the player is unavailable
• Sections view: the full card takes 12 columns by default and at least 6, the mini card 6; narrow widths get their own layout
• Visual editor in the dashboard UI for both cards (no YAML needed)
• Light and dark themes, English, French, German, Spanish, Serbian (Cyrillic and Latin), Italian, Dutch, European Portuguese, Polish, Romanian, Danish, Swedish, Bulgarian, Russian, Ukrainian, Hungarian, Slovak, Czech, Slovenian, Latvian and Greek
• Single file, no external dependency

Supported integrations

Any media_player entity works: the card reads what the player supports. These integrations get more:

Integration	What the cards show
Sonos (core)	Playback, seek, shuffle / repeat, volume per room, groups (join / unjoin), sources (Sonos favorites, line-in, TV), favorites from the Sonos favorites sensor (sensor.sonos_favorites, disabled by default in Home Assistant: enable it), "Track n of m"
Music Assistant (core)	Playback, seek, shuffle / repeat, volume per room, groups (players that can sync), queue (current and next track, queue length, through music_assistant.get_queue), favorites with Music Assistant URIs in the favorites option. Music Assistant also brings AirPlay, Chromecast, Squeezelite, DLNA and Snapcast speakers
Squeezebox (Lyrion Music Server) (core)	Playback, seek, shuffle / repeat, volume, sync groups (join / unjoin)
Google Cast (core)	Playback, seek, volume, app name; Google Home speaker groups are players of their own (no join)
Apple TV (core: Apple TV, HomePod, AirPlay)	Playback, volume, the app playing in the subtitle (else the device's model), the apps as sources, the episode as Series · S1E4, a drawn box or speaker by model; an optional remote (show_remote: true): direction pad, select, menu, home and play / pause through the device's remote entity (remote.send_command). A HomePod is a speaker (volume and playback as it supports them); the integration has no grouping, so there is no join button
Spotify (core)	Playback, seek, shuffle / repeat, volume, Spotify Connect devices as sources
Bluesound, HEOS, LinkPlay, Yamaha MusicCast, Snapcast (core)	Playback, volume, sources, groups (join / unjoin)
Jellyfin (core)	One player per client session: the episode as Series · S2E5 (or Movie), the client app in the subtitle (the session's device model, e.g. Jellyfin Android TV), a drawn TV when there is no artwork; idle sessions (an app left open, nothing playing) are left out of players and of the rooms (hide_idle_sessions)
Alexa Media Player (custom)	Echo speakers and groups: playback, volume, Last called badge (last_called), the next alarm, timer and reminder of the Echo (its Next alarm / timer / reminder sensors) in one line, a do-not-disturb button (its Do not disturb switch), speaker groups (Everywhere, multiroom groups) shown as groups (Alexa cannot join or unjoin speakers from Home Assistant), and Alexa content in favorites (AMAZON_MUSIC, TUNEIN, SPOTIFY…, or custom for a voice command)
Receivers and TVs ( Denon AVR, Yamaha, Samsung TV, LG webOS…)	Power, volume, sources and sound modes, drawn receiver or TV picture

Prerequisites

Home Assistant 2024.8 or later, with at least one media player. The Music Assistant queue needs a Music Assistant integration that has the music_assistant.get_queue action (Home Assistant 2025 and later).

Configuration

Card types#

Visual editor#

Edit a dashboard, click Add card and search for Media Card or Media Mini Card. The first playing player is preselected; pick another one (or several players to show together), the rooms, an optional title, the sections to show and the language. The preview updates live, and options left at their default are kept out of the generated YAML.

Minimal#

type: custom:media-card
entity: media_player.living_room

type: custom:media-mini-card
entity: media_player.living_room

Without entity, the card shows the first player that is playing.

Several players in one card:

type: custom:media-card
players:
  - media_player.living_room
  - media_player.kitchen
  - media_player.bedroom
only_playing: true

Full options#

type: custom:media-card
entity: media_player.living_room
title: Music
entities:
  - media_player.kitchen
  - media_player.office
  - media_player.bedroom
show_title: true
show_subtitle: true
show_background: true
show_progress: true
show_controls: true
show_volume: true
show_rooms: true
show_source: true
show_queue: true
show_favorites: true
collapsed:
  - source
  - queue
  - favorites
favorites_entity: sensor.sonos_favorites
favorites:
  - name: Jazz radio
    media_content_id: http://radio.example/jazz.mp3
    media_content_type: music
  - name: Focus playlist
    media_content_id: library://playlist/12
    media_content_type: playlist
    image: /local/covers/focus.jpg
language: fr

type: custom:media-mini-card
entity: media_player.spotify
title: Spotify
show_progress: true
show_controls: true
show_volume: true
zoom: true
language: fr

Options reference#

Rooms and groups#

The rooms are the speakers of the same integration that can be grouped with the shown player, found by themselves: a Music Assistant player lists the other Music Assistant players, a Sonos speaker the other Sonos speakers. List them yourself with entities to pick or order them, or to show players of several integrations (their volume only: a group only joins players of one integration).

• The link button of a room joins it to the group of the shown player (to the group's leader, the first of its group_members), or takes it out. The new membership shows at once, until the integration reports it.
• Ungroup all takes every other speaker out of the group, after a confirmation.
• A click on a room's name shows that player in the card (the title then follows it); a click on the configured player's name brings it back.

Several players#

With two players or more in players, the card shows them together, in the order of the list:

• The Media Card stacks a block per player, separated by a thin line: artwork, track, progress, the controls the player supports, volume and mute. The header gives the card's title (title, Media by default), how many players it has and how many play. A click on a player's name opens it in the full view (rooms and groups, source, queue, favorites), with a back button to the stack.
• The Media Mini Card lists them one per row: artwork, name, track, play / pause and a small volume slider. A click on a row unfolds it (progress, every control, volume with its percentage); a click elsewhere on the page folds it back. The detail button switches to the stacked view.
• only_playing: true keeps the players that are playing (add include_paused: true for the paused ones); the others are named in one line at the bottom, a click on it shows them too.

title, show_progress, show_controls and show_volume apply to every player. Without players (or with a single one), the cards behave exactly as with entity.

Only the players that are playing (only_playing), the others in one line at the bottom:

The mini card lists them one per row; a click on a row unfolds it:

Jellyfin and Alexa#

A Jellyfin session shows the episode and the client app; an Echo its Last called badge, its next alarm and timer, and a do-not-disturb button. Stacked with other players, an idle Jellyfin session (here a web browser left open) is left out and named at the bottom:

Alexa favorites go through media_player.play_media like any other: a music provider and a search, or a voice command.

type: custom:media-card
entity: media_player.kitchen_echo
favorites:
  - name: Morning jazz
    media_content_id: morning jazz playlist
    media_content_type: AMAZON_MUSIC
  - name: Radio
    media_content_id: France Inter
    media_content_type: TUNEIN
  - name: Good night
    media_content_id: turn off the lights and play rain sounds
    media_content_type: custom

The do-not-disturb switch and the next alarm, timer and reminder sensors are found on the Echo's device (Alexa Media Player creates them; a disabled sensor is simply not shown).

Apple TV and HomePod#

The Apple TV shows the app playing, the episode and its apps as sources; show_remote: true adds the remote. A HomePod is a speaker:

type: custom:media-card
entity: media_player.living_room_apple_tv
show_remote: true

On the mini card, show_remote: true adds a remote button to the compact view; it opens the remote in a popup at the top of the card, which stays open while its keys are pressed:

type: custom:media-mini-card
entity: media_player.living_room_apple_tv
show_remote: true

Drawn pictures#

With no artwork, the card draws the device. Echo speakers and displays, HomePods and Apple TV boxes get a picture of their own, chosen from the model of their device in Home Assistant's device registry (tolerant: case, spacing and generation suffix do not matter); any other player keeps the speaker, TV or receiver picture of its device_class. These are original, stylized silhouettes of the general shape of each device, with no logo or brand. Only their lights move, and only while playing (a soft pulse, stopped by prefers-reduced-motion); the bodies follow the light or dark theme.

Each one has a dark twin (picture-…-dark.gif); the small mesh speaker straight on in the mini card: picture-homepod-mini-front.gif.

How it works

What the card draws follows the supported_features of the player:

The services called are the standard media_player ones (media_play, media_pause, media_seek, volume_set, select_source, join, unjoin, play_media…), plus music_assistant.get_queue for the queue. The progress moves with media_position and media_position_updated_at, without a request every second. The artwork is read from entity_picture_local (the Home Assistant proxy) or entity_picture.

Support

If you find this project useful, you can support its development:

Fixes

• A click could do nothing: Home Assistant updates the card several times a second, and a rewrite of the card between the press and the release replaced the element pressed, so that the click was lost (most visible on Show less of the hidden players, which then seemed stuck). The card is no longer rewritten while a press is in progress; the pending update is drawn right after the click.
• The hidden players (only_playing) hide again when the card folds back: a tap elsewhere, the mini card back to its compact view, or the card leaving the page.
• No focus ring after a mouse click or a tap: the focus is kept across updates only for the keyboard.

Fixes

• Folding back on a tap elsewhere now works on iOS (Safari and the companion app): a tap on something that is not clickable sent no click to the page, so the detailed view of the mini card, the unfolded sections, the unfolded rows of the players and the remote popup stayed open. The press and the release are caught instead; a slider dragged out of the card and a scroll do not fold anything.
• Leaving the card (another dashboard view, a conditional card hidden) brings it back in its default state: sections folded as configured, popup closed, mini card compact.

Features

• Apple TV mini card: with show_remote: true, a remote button sits before the controls of the compact view; it opens the remote (direction pad, select, menu, home, play / pause) in a popup at the top of the card, which stays open while its keys are pressed and closes with its cross, Escape or a click elsewhere. The detailed view keeps its remote section.
• The Close the remote text in the 22 languages.

Features

• Jellyfin: an episode shows its series and episode (Series · S2E5), a film shows Movie, the subtitle names the client app (the session's device model) and a session with no artwork draws a TV.
• hide_idle_sessions (default on): Jellyfin sessions with nothing playing are left out of players (named in the line at the bottom) and of the rooms.
• Alexa Media Player: Last called badge, the Echo's next alarm, timer and reminder in one line, a do-not-disturb button (its Do not disturb switch), Alexa speaker groups (Everywhere, multiroom) shown as groups; the mini card and the stacked players get the compact line.
• Alexa content in favorites documented (AMAZON_MUSIC, TUNEIN… or custom for a voice command).
• Apple TV: the app playing in the subtitle (else the device's model), the episode (Series · S1E4), the apps as sources, and an optional remote (show_remote): direction pad, select, menu, home and play / pause through the device's remote entity.
• HomePod: a speaker, with the controls it supports and no join button (the integration has no grouping).
• Device pictures: with no artwork, Echo speakers and displays, HomePods and Apple TV boxes are drawn from their device model (cylinder, large cylinder, sphere, puck, half sphere, display, small display, tall and small mesh speakers, streaming box): original stylized silhouettes with no logo or brand, whose lights pulse while playing; the small mesh speaker is seen from above in the full card and straight on in the mini card.
• Visual editors: the Hide idle Jellyfin sessions and Show the remote options; the new texts in the 22 languages.
• Other players render exactly as before.

Features

• Several players (players): with two media players or more, the Media Card stacks a block per player (artwork, track, progress, controls, volume) under a common header that counts the players and the ones playing; a click on a player's name opens it in the full view (rooms, source, queue, favorites), with a back button to the stack.
• The Media Mini Card lists the players one per row (artwork, name, track, play / pause, volume); a click on a row unfolds it (progress, every control, volume), and the detail button switches to the stacked view.
• only_playing: only the players that are playing (include_paused adds the paused ones); the others are named in one line at the bottom that shows them on click, and the player that changed last is shown when none plays.
• Visual editors: players, only playing and paused players options; their texts in the 22 languages.

Features

• Media Card (custom:media-card): artwork with a blurred artwork background, title, artist and album, progress bar (click or arrow keys to seek), transport controls (power, shuffle, previous, play / pause, next, repeat), volume slider (or - / + buttons) and mute.
• Rooms and groups: every speaker of the integration that can group (or the players of the entities option) with its own volume; a link button joins a room to the shown player's group or takes it out (media_player.join / unjoin), "Ungroup all" asks first in a popup at the top of the card, and a click on a room shows that player in the card.
• Source and sound mode chips (select_source, select_sound_mode).
• Queue of Music Assistant players (music_assistant.get_queue): current and next track and the queue length; a click on the next track skips to it.
• Favorites: the favorites option (any play_media content) and the Sonos favorites sensor, found by itself or given by favorites_entity.
• Media Mini Card (custom:media-mini-card): artwork, track, previous / play-pause / next, progress and volume; its detail button switches to the full card and back.
• Everything follows the player's supported_features: a control the player cannot take is not drawn.
• Animations for each state: the record slides out of its sleeve and turns while playing, the equalizer bounces (playing) or glows (paused), a ring turns while buffering, the drawn speaker beats and sends sound waves, the TV screen glows, and the playing rooms of a group ring; all of them honour prefers-reduced-motion.
• Drawn speaker, TV and receiver pictures for players without artwork.
• Visual editors for both cards, light and dark themes, 22 languages (English in the bundle, each other language loaded on demand).