Widget

Media

A now-playing card for one — or many — Home Assistant media_player entities. Artwork, transport, a live progress bar, volume, a multi-speaker picker that can join speakers into one synced group, quick-source favorites, and a unified browser spanning Home Assistant, Plex, NAS, and Apple Music. The card adapts to its tile size and draws identically on iPhone, iPad, and Apple TV.

What it does

The widget shows the now-playing state of the speakers you point it at: title, artist / show / app, album art, and transport controls. Any HA media player works — Sonos, Alexa, HomePod, a receiver, an Apple TV, a Music Assistant player — they're all just media players to Home Assistant. You add several to one widget and pick which ones to control at runtime; every command fans out to your current selection, so a mixed Sonos + Alexa + HomePod group all obey play, pause, skip, and volume together.

The card has four layouts that switch on tile size: a micro tile (play button, maybe a title), a compact row, the standard card (art beside text with transport and volume), and a tall hero (big artwork on top). Bigger tiles reveal more — the progress bar, then the volume slider, appear as height allows.

One widget, many speakers The widget's entities are its speaker pool. You choose 1…all of them from the speaker button, and that choice is saved and synced across your devices. There's always at least one speaker selected (the first source is the fallback).

Add it

Enter edit mode, tap Add Widget, choose Media.
Open the widget's inspector (tap the widget while editing) and add your media_player entities as the speaker pool.
Optionally add favorites / quick sources, turn on Apple Music, and pick the playing animation.

You don't have to add every speaker up front — the speaker picker can add any other HA media player on the spot (see below).

Speakers & multi-room

The speaker button (a hi-fi-speaker chip showing the selected count) opens the Play on picker:

Tap speakers to toggle them in or out of the selection. Each selected speaker gets its own per-speaker volume slider right in the list (committed on release, so a drag doesn't flood Home Assistant).
All speakers selects the whole pool at once.
Add a speaker lists every other HA media player not yet on the widget (Music Assistant, Alexa, Sonos, receivers…). Picking one adds it to the widget and to the selection — no need to leave the card.

Grouping (multi-room): when two or more speakers are selected, Group these speakers joins them into one synced group via Home Assistant's media_player.join — the first selected speaker becomes the master, the rest become its group members, so they all play one stream perfectly in sync (Sonos, AirPlay 2, Music Assistant…). Ungroup calls media_player.unjoin on each selected speaker. Speakers Flux recognizes as AirPlay-2 capable (Sonos, Apple TV, HomePod) are tagged with a badge — informational only.

The card shows the metadata of whichever selected speaker is actually playing (falling back to the first selected). When more than one speaker is selected, the subtitle notes "· N speakers".

Selecting vs. grouping Selecting multiple speakers just means "send my taps to all of these." Grouping additionally tells the speakers themselves to play one synced stream. You can do either or both.

Sources

There are two ways to start something playing.

Quick sources (favorites)

The music-note-list chip opens your Sources list — one-tap favorites you configure in the inspector. A favorite can be:

a speaker input source (from the speakers' own source_list — receiver inputs, Sonos favorites, Music Assistant sources) → calls select_source; the active input gets a checkmark;
a custom media id / URI (a stream URL, a Music Assistant playlist/track, a Spotify URI via Music Assistant…) → calls play_media;
an Apple Music item (a pinned song, album, or playlist) → plays locally via MusicKit (iOS).

Each favorite can optionally pin its own target speakers ("play X on Y"); otherwise it acts on your current selection. Choosing a favorite with pinned targets makes those speakers the card's selection.

Browse (the unified browser)

The stacked-squares chip opens the unified media browser — one surface with four tabs:

Music — Apple Music: browse and search the catalog of the account signed in on this device.
Home — the Home Assistant media library tree (folders, anything HA exposes, including NAS shares mounted in HA). The chosen item plays on the widget's selected speakers via play_media.
Plex — pick a server, drill into libraries and items. The selected item's Plex stream URL is handed to the selected speakers via play_media (typed video or music). Sign in under Settings → Media → Plex.
NAS — pick a saved server → share → folder → file. NAS files play locally on this device in a built-in player (speakers can't read SMB); the file is downloaded to temp and removed when the player closes. Add a NAS under Settings → Media → Network Storage.

Where playback lands Home Assistant and Plex items play on the selected speakers. NAS files and Apple Music play locally on the device you're holding — Apple Music routes through the system AirPlay / Bluetooth picker, not HA. This split is deliberate: speakers can't read SMB, and Apple Music DRM is local-only.

Apple Music

Turn on Apple Music in the inspector to add "This device · Apple Music" to the speaker picker. Picking it swaps the card to a full Apple Music controller — local play/pause, skip, shuffle, repeat, a scrubbable progress bar, album art, an AirPlay route picker, the browse button, and a visualizer. An explicit speaker choice always wins, so picking HA speakers or "All speakers" reliably leaves Apple Music. (Apple's DRM blocks reading the live audio, so the visualizer animates with playback rather than the real waveform.)

Settings

Option	What it does
Show artwork	Draw the album art chip / hero. Off → text-only card (the equalizer moves inline instead).
Artwork as background	Fill the whole tile with the art behind a dark scrim; text and controls go white.
Volume slider	Show the volume control. On Apple TV it's −/+ step buttons (no slider on tvOS).
Progress bar	Show the live position / duration bar. It advances locally in real time while playing. (Defaults on; only appears on tall-enough tiles.)
Playing animation	While music plays: Equalizer bars, Pulsing artwork (art breathes), Spinning vinyl (art becomes a turning record), or None. Defaults to bars.
Speakers (selection)	Which of the pool's entities commands target. Saved and synced across devices; falls back to the first source.
Favorites & quick sources	The one-tap source tiles: speaker inputs (from `source_list`), custom media ids / URIs, or pinned Apple Music items — each optionally bound to specific speakers.
Play Apple Music on this device	Adds "This device · Apple Music" to the picker and enables local MusicKit playback (iOS only).
Visualizer (Apple Music)	The animation on the Apple Music card: None, Equalizer bars, Flowing wave, Floating orbs, or Pulse rings.

Transport that reads the player Shuffle and repeat only appear when the player advertises them (supported_features). For a device that supports turn-on (Apple TV, receiver, TV), pressing play wakes it first, so audio doesn't quietly resume behind a screensaver. Artwork is fetched with your HA token, so token-required images (Apple TV, YouTube) actually load.

On Apple TV The card draws the same, but tvOS skips the slider and uses focusable −/+ volume buttons and full-screen pickers. Saved speaker selections are still honored.