Beacon Docs

Music

Beacon lets you control any media player entity in Home Assistant directly from your wall-mounted display. This includes Music Assistant, Sonos, Google Home speakers, Chromecast, and any other media player integration.

Music Assistant setup in Home Assistant

Music Assistant is the recommended way to manage music in Home Assistant. It provides a unified interface for Spotify, YouTube Music, local files, and more.

Step 1: Install Music Assistant

  1. Go to Settings > Add-ons > Add-on Store
  2. Search for Music Assistant
  3. Click Install
  4. Start the add-on

Step 2: Configure Music Assistant

  1. Open the Music Assistant web UI
  2. Add your music providers (Spotify, YouTube Music, local files, etc.)
  3. Add your player providers (Sonos, Chromecast, AirPlay, etc.)

Step 3: Verify in Home Assistant

Music Assistant creates media_player.* entities for each configured player:

  • media_player.living_room_speaker
  • media_player.kitchen_speaker
  • media_player.bedroom_speaker

Verify they exist in Developer Tools > States.

Alternative: Other media player integrations

Beacon works with any media_player.* entity, not just Music Assistant. Other supported integrations include:

  • Sonos (built-in HA integration)
  • Google Cast (Chromecast, Google Home speakers)
  • Apple TV / AirPlay
  • Plex
  • Kodi
  • VLC
  • Generic media players

Full music view

Open the music view by clicking the music note icon in the sidebar (or tapping Music in the mobile tab bar).

The music view displays:

Player selector

When you have multiple media players, a dropdown appears at the top. Click it to see all available players and switch between them. Players that are currently playing show a “Playing” indicator.

Album art

A large album art image is displayed in the center. If the current track has no artwork, a placeholder icon is shown.

The album art URL is fetched from the media player’s entity_picture attribute. For local HA URLs, the Home Assistant base URL is prepended automatically.

Track info

Below the album art:

  • Title: The current track name (or “Nothing Playing” if idle)
  • Artist: The artist name
  • Album: The album name (if available)

Progress bar

A progress bar shows the current playback position:

  • Left timestamp: Current position (e.g., “2:45”)
  • Progress bar: Visual indicator of position within the track
  • Right timestamp: Total duration (e.g., “4:30”)

The progress bar updates every second while playing, using a local timer for smooth animation. The position syncs back to the actual media player position whenever the HA state updates.

Transport controls

Three buttons in a row:

  • Previous (skip back icon): Go to the previous track
  • Play/Pause (play or pause icon, larger): Toggle playback
  • Next (skip forward icon): Go to the next track

Volume control

A volume section at the bottom:

  • Mute/Unmute button: Click to toggle mute. Shows a speaker icon (normal) or crossed-out speaker (muted)
  • Volume slider: Drag to set volume from 0% to 100% (values 0.0 to 1.0)

Now Playing bar

When music is playing on any media player, a persistent “Now Playing” bar appears at the bottom of the screen. This bar is visible on the Dashboard, Calendar, Chores, and other views — but not on the Music or Photos views.

The Now Playing bar shows:

  • Album art thumbnail: Small image on the left
  • Track info: Title and artist
  • Transport controls: Previous, Play/Pause, Next
  • Volume slider: Compact volume control

Expanding to full view

Click on the album art or track info area of the Now Playing bar to open the full Music view.

When does the bar appear?

The bar appears whenever any media_player.* entity has a state of playing. It disappears when all players are paused, idle, or off.

Player selection

If you have multiple media players:

  1. Open the full Music view
  2. Click the player name dropdown at the top
  3. A list of all discovered media players appears
  4. Players currently playing show a “Playing” badge
  5. Click a player to select it

The selected player becomes the active player for all transport and volume controls. If no player is explicitly selected, Beacon automatically selects the first player that is currently playing.

Player priority

Beacon resolves the active player in this order:

  1. Any player with state playing
  2. The explicitly selected player (via the dropdown)
  3. The first player in the list

Volume control

Volume is controlled through Home Assistant’s media_player.volume_set service:

  • The slider range is 0.0 (silent) to 1.0 (maximum)
  • The slider step is 0.02 (2% increments)
  • Clicking the speaker icon sends volume 0 (mute) or restores the previous volume level
  • Volume changes take effect immediately on the physical speaker

Real-time updates

Beacon subscribes to Home Assistant’s state_changed event for all media_player.* entities. When a media player’s state changes (new track, volume change, play/pause, etc.), Beacon updates the UI immediately without waiting for the next polling interval.

This means:

  • Changing volume on the physical speaker updates the Beacon slider
  • Starting playback from Spotify shows the track in Beacon within 1-2 seconds
  • Skipping tracks from any control surface (phone app, voice assistant) reflects in Beacon

Troubleshooting

No players appear

  1. Verify you have media_player.* entities in Home Assistant: Developer Tools > States, filter by “media_player”
  2. Check that Beacon is connected to HA (no “Connecting…” badge)
  3. Some media players only appear when powered on — if a speaker is off, its entity may not be listed

Album art does not load

  1. Album art URLs from HA are often relative paths (e.g., /api/media_player_proxy/...)
  2. Beacon prepends the HA URL to relative paths, so ha_url must be correctly configured
  3. If running Beacon on a different domain/port than HA, CORS restrictions may block the image

Controls do not respond

  1. Check the browser console for errors
  2. Verify the media player supports the service being called (some players do not support skip/previous)
  3. Test the service in Developer Tools > Services: call media_player.media_play on the entity

Volume slider jumps around

This can happen when the physical speaker and Beacon disagree on the volume level. Each volume change triggers a state update from HA, which may briefly conflict with the local slider position. The slider will settle after 1-2 seconds.

Was this page helpful?

Give Feedback