-
-
Notifications
You must be signed in to change notification settings - Fork 20
Music Playback
Ava can serve as a Home Assistant media player, playing music and voice announcements. It also supports Music Assistant integration via Sendspin for multi-room audio sync.
0.5.9+ added a detailed music player with synced lyrics, reorganized media/volume settings, and a Mini player cover ring. 0.6.0 made the progress bar seekable and fixed lyric/progress edge cases. 0.6.2 introduced explicit Volume Follow Rules and unified media overlay pause behavior. 0.6.4 switches the primary lyrics source to LRCLIB, tightens duration/artist matching, and adds pause-recovery for the media overlay. 0.6.5 added Expanded Lyrics (full-screen lyrics wall), a five-band equalizer for HA and MA, and a more enduring browser during music. 0.6.6 added Lyrics Focus, Karaoke Lyrics (Beta), and a speech gate for wake word. 0.6.8 integrated the Music Assistant WebSocket API as a full music console with queue management, playback transfer, and per-device sync delay. 0.6.9 added per-device sync delay calibration, lyric offset/follow controls, expressions that follow the reply, and a redesigned update page. 0.7.3 added an adaptive loudness contour to the equalizer and stable playback group identities for Sendspin.
Ava supports the following audio features:
- Media playback (music, podcasts, etc.)
- TTS voice announcements
- Wake prompt sounds
- Timer sounds
- Music Assistant multi-room sync (via Sendspin)
In Home Assistant, Ava registers as a media player entity:
media_player.your_device_name
| Operation | Description |
|---|---|
| Play | Play media |
| Pause | Pause playback |
| Stop | Stop playback |
| Volume | 0-100% |
| Mute | Enable/disable mute |
service: media_player.play_media
target:
entity_id: media_player.your_device_name
data:
media_content_id: "http://example.com/music.mp3"
media_content_type: "music"| Format | Description |
|---|---|
| MP3 | Most common |
| AAC | Apple format |
| OGG | Open source format |
| WAV | Lossless format |
| FLAC | Lossless compressed |
- HTTP/HTTPS URLs
- Local file paths
- Streaming URLs
When playing music, Ava can display beautiful vinyl record style album covers.
- Go to Settings -> Interaction
- Find Media Player
- Turn on Home Assistant Media Controls or Music Assistant Media Controls
Set the Home Assistant media player entity ID for album art:
- Go to Settings -> Interaction -> Media Player
- Find Home Assistant Media Player
- Enter entity ID, e.g.
media_player.xxx - Album art only works when album display is enabled
service: esphome.your_device_name_media_cover
data:
url: "http://example.com/cover.jpg"The music overlay offers two styles. Synced lyrics are not shown in the default Minimal style; switch to Full metadata to enable them.
| Style | Description |
|---|---|
| Minimal (default) | Compact album-art presentation. |
| Full metadata | Larger playback metadata, progress and transport controls, plus time-synced lyrics when a matching lyric is available. |
The detailed layout adapts to different screen sizes and orientations. Lyrics follow the current playback position and can be fine-tuned from the player when their timing needs adjustment. Tracks without a lyric match continue to use the normal metadata layout.
Path: Ava Settings → Interaction → Media Player → Media Overlay Style → Full metadata
The Full metadata interface also keeps the display awake during playback, so the screen no longer turns off while viewing lyrics or using media controls (0.6.0).
During Music Assistant / Sendspin playback, the progress bar in the Full metadata interface is directly seekable. Tap any point to jump to that position in the track; the player updates progress and lyrics immediately, then reconciles with the server's confirmed playback position without snapping back or losing lyric alignment.
Known upstream limitation: Ava can send the seek command to Music Assistant / Sendspin, but some upstream versions do not yet return the exact resulting playback position to Ava. In that case, Ava can update its local progress from the user's tap but cannot always confirm the final position with the server. Full reconciliation depends on the upstream protocol interface being completed over time.
Synced lyrics now follow the audio that is actually heard more closely, accounting for Sendspin playout buffering and the user's synchronization offset. Matching adds retries, a fallback query and duration validation to reduce failures and incorrect results caused by network errors, missing artist data or similarly named tracks.
Fixes in 0.6.0: lyrics starting midway after a track change, jumping to the first line after pausing, delayed timing adjustments, and local progress becoming stuck after an upstream seek. Cover and lyric changes also use softer transitions.
The Detailed player is no longer only a place for cover art. It can become a proper lyrics wall. Tap the cover to enter Expanded Lyrics: the current line stays prominent, surrounding lines dissolve naturally, and portrait and landscape layouts rearrange the cover, title, artist, and lyrics around the most comfortable reading area.
Swipe up or down to browse the lyrics; after a moment, the view returns to the line being sung. Tap any line to adjust lyric timing. With Music Assistant / Sendspin, double-tap a line to start playing from that point. Tap the cover again to return to the full player.
When music is paused, the mini overlay moves out of the way and gives the screen back to what you were doing. Once playback truly resumes, it returns naturally with the current song.
Building on 0.6.5 Expanded Lyrics, the Detailed Metadata player adds Lyrics Focus: tap the cover to switch between the full player and full-screen lyrics (off by default to save resources). When expanded, lyrics follow the current line in the center; scroll to browse and double-tap a line to resume playback from there. Portrait and landscape remember whether you expanded until you tap the cover again.
Path: Ava Settings -> Interaction -> Media & Playback -> Detailed metadata
Optional Karaoke lyrics: the active line lights up left to right with the vocal, with softer line transitions and less reliance on zoom to keep time.
QQ Music and LRCLIB search together with stricter matching: fewer wrong songs, less confusion between live and studio versions, and no forced lyrics when artist metadata is incomplete.
0.6.7 adds community AMLL word-synced lyrics. Ava searches AMLL, LRCLIB, and QQ Music together, then considers the title, artist, album, and duration before choosing. Results arrive sooner and are less likely to confuse a studio track with a live version or another song with the same name.
Path: Ava Settings -> Interaction -> Media & Playback -> Karaoke lyrics (Beta)
When a song reaches an instrumental passage, the previous line should not hang around until the singer returns. Ava now turns timed gaps in the middle of a song into a gently filling ♪ display. Longer breaks receive a few more marks; when the song is ending, the lyrics simply settle without adding stray notes.
Long English lines, rap verses, and narrow screens now move more smoothly instead of stopping and jumping. In portrait, title and artist have separate lines so long metadata no longer becomes a crowded block.
After pausing, tucking away the player, or briefly losing a music source, reopening the player could show an old title or forget the position and duration. Ava now remembers the cover, song, and position that were actually playing. Resume brings back the familiar view; only a real track change clears it.
Seeking, jumping backward, or changing tracks in Music Assistant also moves the player and lyrics to the right place. While the Detailed Metadata player is open for lyrics, the screensaver stays out of the way.
Ava Pro includes a custom five-band equalizer for both Home Assistant music output and Music Assistant / Sendspin. Each source receives an independent equalizer.
| Band | Frequency |
|---|---|
| 1 | 80 Hz |
| 2 | 250 Hz |
| 3 | 1 kHz |
| 4 | 4 kHz |
| 5 | 10 kHz |
Each band is adjustable from -10 dB to +10 dB. Each music source remembers its own curve and changes take effect immediately. The equalizers are disabled by default and do not alter TTS, wake sounds, or calls. Use matching curves across a synchronized group for a consistent multi-room sound.
The equalizer now includes an optional adaptive loudness contour that automatically adjusts bass and treble response based on how loud the room is. At low volumes, the human ear loses sensitivity to bass and treble — the adaptive contour compensates so music sounds balanced at any listening level.
- Bass lift increases as volume drops, restoring warmth at quiet levels
- Treble lift follows the same curve, keeping detail audible at low volume
- At normal-to-loud volumes, the contour flattens out — no coloration when you don't need it
- The contour adapts smoothly with separate rise and fall speeds, so volume changes don't produce audible EQ jumps
- Quantized in fine steps to avoid zipper noise
The adaptive contour is independent from the manual band gains. Both can be used together — the manual curve shapes your preferred sound, and the adaptive contour refines it for the current volume.
Path: Ava Settings -> Interaction -> Media & Playback -> Home Assistant / Music Assistant -> Audio equalizer -> Adaptive contour
0.6.8 formally integrates the Music Assistant WebSocket API. After sign-in, a touch-friendly music rail opens beside the detailed player. See Sendspin → Music Assistant Console for full details.
Highlights:
- Browse playlists, play the whole list or one song
- See Up Next and rearrange the queue
- Transfer playback to another room
- Adjust room volume and sync delay per device
- Sleep timer, repeat, shuffle, autoplay, favorites
- Adapts to phone, portrait, landscape, and tablet layouts
Path: Ava Settings -> Interaction -> Media & Playback -> Music Assistant sign-in
The music console includes lyric controls for fine-tuning when lyrics don't quite match the audio.
| Control | Range | Description |
|---|---|---|
| Offset | -500 ms to +500 ms | Moves lyrics earlier or later. Changes appear immediately and are remembered. |
| Follow | 5 levels | Controls how quickly lyrics return to the current line after scrubbing, skipping, or a brief network disturbance. |
Follow levels: Steady → Calmer → Default → Closer → Tight
With the three-line lyric view, tapping the lyrics also reveals a temporary fine-adjustment bar without leaving the player.
The orb can show happy eyes for good news and different expressions for an apology or an important warning. During a long answer, the expression can change as the captions move to the next page. The eyes change during a blink while the orb color stays steady. The text is evaluated directly on the device.
- When music is paused, the progress bar holds at the audible position. After resuming, progress moves again when sound actually returns.
- Scrubbing keeps lyrics and the progress bar closer to what is playing.
- If a playlist briefly stalls while moving naturally to the next track, playback can recover. A pause requested by the user remains paused.
- When the network slows and Music Assistant cannot return the queue in time, the current cover and progress remain visible.
- After Sendspin reconnects, a later outage begins again with a short retry delay.
- When the player opens before a song arrives, it shows a waiting state. If no media arrives, the overlay closes itself.
- At a track change, the cover and backdrop move naturally to the next song.
- After the player collapses into the music orb, hidden lyrics and backdrop animation stop refreshing.
- While scrubbing, reading lyrics, or using a player control, the surface remains present instead of hiding halfway through the action.
When MA is connected, Ava can use its synchronized lyrics and quietly prepare several tracks around the one currently playing. Reopening the player or skipping to another song finds the lyrics already waiting instead of loading them from scratch.
The music mini button no longer fails to reappear after auto-hide when playback starts again. Floating subtitle reliability is also improved.
- In portrait, the entire right edge no longer opens the music console over the lyrics. A touch can reveal the handle, and the visible handle can then be tapped to enter.
- Long song and artist names adapt to the available room instead of sending both lines across the screen at once.
LRCLIB is now Ava's primary lyrics source. A request that times out after 5 seconds, returns no useful result, or fails validation automatically falls back to QQ Music; the QQ Music path also performs one short retry when needed.
Matching improvements:
- Track duration and multiple artists are considered more carefully, reducing cases where a different recording with the same title supplies the lyrics
- Known spoken-track and no-lyrics placeholders are filtered out
- A track without artist metadata no longer inherits the previous track's artist
Smoother sync: small one- or two-second progress corrections from the upstream player now use hysteresis, keeping the lyric window from jumping backward and forward around a line boundary. Deliberate, larger seeks still realign the lyrics immediately.
The Mini player control lets the full music interface collapse smoothly into a circular cover ring at the edge of the screen instead of disappearing or occupying the whole display.
- The ring shows album art, playback progress and play/pause state.
- The cover rotates slowly while playing, coasts and returns upright after pausing, and crossfades when the track changes.
- Tap the center to play or pause; tap the rest of the cover to reopen the full player.
- The control can be dragged to a convenient position and remembers its placement across portrait and landscape layouts.
- Track changes, pauses and brief metadata gaps preserve the user's expanded or collapsed state.
- It only fades away after the playback queue is genuinely empty and a grace period has elapsed.
This also completes the last mile between music and the kiosk browser: collapse the full player into the cover ring to reveal weather, shopping lists, radio selectors or other browser pages while playback and essential controls remain available.
Path: Ava Settings → Interaction → Media Player → Mini player control
service: tts.speak
target:
entity_id: media_player.your_device_name
data:
message: "Hello, welcome home"Ava uses the TTS engine configured in Home Assistant. Recommended:
- Piper (local, fast)
- Google TTS (online, good quality)
- Azure TTS (online, good quality)
service: media_player.volume_set
target:
entity_id: media_player.your_device_name
data:
volume_level: 0.8 # 0.0 - 1.0service: media_player.volume_mute
target:
entity_id: media_player.your_device_name
data:
is_volume_muted: trueVolume synchronization now provides three explicit, mutually exclusive modes:
| Mode | Key | Behavior |
|---|---|---|
| Independent | independent |
Device and Home Assistant volumes are adjusted separately. Default for new installations. |
| Follow device | follow_device |
Changes made with the device volume keys are sent to Home Assistant. |
| Follow Home Assistant | follow_ha |
Volume changes in Home Assistant are applied to the device. |
Only one follow direction can be active at a time, preventing the device and Home Assistant from repeatedly overriding each other. Existing users who enabled the previous volume-key synchronization option are migrated to Follow device.
The same setting is available on the device and in the Ava Fleet console.
Path: Ava Settings → Interaction → Media Player → Volume Follow Rule
The previous Sync with volume keys option (0.5.9) and the older Device Volume / Software Volume mode selector (removed in 0.5.9) are both superseded by this rule. The legacy boolean
syncDeviceVolumeWithHais migrated automatically whenvolumeFollowRuleis still blank.
The Home Assistant media player and Sendspin now share the same pause behavior.
Home Assistant can now display or hide Ava's expanded music overlay through a dedicated switch. The switch and the current expanded state remain synchronized in both directions.
- Turning the entity on opens the expanded player
- Turning it off collapses to the mini player when appropriate, or hides the overlay while preserving the current media session and metadata
- Only the expanded player is reported as active — the mini floating button does not leave the Home Assistant switch incorrectly enabled
Path: Ava Settings → Interaction → Media Player → Show in Home Assistant
- About 10 seconds after playback is paused, an expanded mini player collapses into its floating button; if playback remains paused, it is then hidden temporarily.
- When the mini player is disabled, the full overlay hides after the same initial delay.
- Repeated paused states no longer keep resetting the timer.
- Resuming playback immediately cancels the hide task and restores the previous title, artwork, progress, and floating-button position.
- Fade transitions now run on the Compose drawing layer, improving reliability on vendor systems where View alpha animations were inconsistent.
The media overlay no longer gets caught between a paused state and its idle timer.
- In minimal mode with the floating button disabled, pausing playback now fades the overlay out after 20 seconds
- If the upstream player is still not ready to resume 10 seconds later, Ava clears stale title/artist identity and waits for fresh metadata instead of leaving old media information stuck on screen
- With the floating button enabled, or when using the detailed player, the established 10-second pause behavior is unchanged
- Resuming playback cancels the pending cleanup
Display text content of voice conversations as a floating window.
- Go to Settings -> Interaction
- Turn on Floating Subtitle switch
Ava supports Music Assistant for multi-room audio sync via the Sendspin protocol. See Sendspin for detailed setup.
| Setting | Description |
|---|---|
| Music Assistant Media Controls | Show music controls during Music Assistant playback |
| Sendspin Optimization Mode | Recommended for low-memory devices |
| Sendspin Sync Offset | Fine-tune playback timing in milliseconds |
| Sendspin Audio Format | Audio codec and quality |
| Sendspin Device Name | Name shown on Music Assistant server |
| Volume Follow Rule | Independent / Follow device / Follow HA (see Volume Follow Rules) |
The previous Device Volume / Software Volume selector was removed in 0.5.9. Ava now uses one consistent device media-volume path for Music Assistant and physical volume keys. The previous Sync with volume keys option (0.5.9) was replaced by the three-way Volume Follow Rule in 0.6.2.
| Setting | Location | Description | Default |
|---|---|---|---|
| HA Media Player | Interaction -> Media Player | Entity ID for album art | - |
| HA Media Controls | Interaction -> Media Player | Show music controls | Off |
| Music Assistant Media Controls | Interaction -> Media Player | Show MA music controls | Off |
| Media Overlay Style | Interaction -> Media Player | Minimal / Full metadata (synced lyrics) | Minimal |
| Mini player control | Interaction -> Media Player | Collapse full player into cover ring | Off |
| Volume Follow Rule | Interaction -> Media Player | Independent / Follow device / Follow HA | Independent |
| Five-Band EQ (HA) | Interaction -> Media & Playback -> Home Assistant | Per-band -10 to +10 dB | Off |
| Five-Band EQ (MA) | Interaction -> Media & Playback -> Music Assistant | Per-band -10 to +10 dB | Off |
| Karaoke Lyrics (Beta) | Interaction -> Media & Playback | Word-by-word highlight | Off |
| Music Assistant Sign-in | Interaction -> Media & Playback -> Music Assistant | Account / mTLS for MA console | Off |
| Lyric Offset | Music console | -500 to +500 ms | 0 ms |
| Lyric Follow | Music console | Steady → Tight (5 levels) | Default |
| Floating Subtitle | Interaction | Show conversation text | Off |
service: media_player.play_media
target:
entity_id: media_player.your_device_name
data:
media_content_id: "http://example.com/music.mp3"
media_content_type: "music"service: media_player.media_pause
target:
entity_id: media_player.your_device_nameservice: media_player.media_play
target:
entity_id: media_player.your_device_nameservice: media_player.media_stop
target:
entity_id: media_player.your_device_nameservice: media_player.volume_set
target:
entity_id: media_player.your_device_name
data:
volume_level: 0.8- Check if URL is accessible
- Check if audio format is supported
- Check if volume is muted
- Check Home Assistant connection
- Check if Media Controls is enabled
- Check if HA Media Player entity ID is set correctly
- Check network connection
- Try manually setting cover URL
- Increase volume in Ava settings
- Increase device system volume
- Check if mute is enabled
See Sendspin for multi-room sync configuration. Adjust Sendspin Sync Offset in Settings -> Extensions -> Media Player.
Back to Home
- Quick-Start
- System-Requirements
- Voice-Control
- Chorus-Wake
- ESPHome-Encryption
- HA-Direct-Connection
- Browser
- Screensaver
- Floating-Windows
- Home-Launcher
- Home-Screen-Widgets
- Notification-Scenes
- Quick-Entity
- Sensors
- Backup
- Sendspin
- Bluetooth
- Voice-Messages-Calls
- Music-Playback
- Camera
- Screen-Control
- Intent-Launcher
- ADB-Commands
- Mod-Store
- Ava-Fleet