HOMEii Music Flow 5.9.3

HOMEii Music Flow 5.9.3

Release date: 2026-06-20

HOMEii Music Flow 5.9.3 is a focused stability release for the open 5.9.x support reports. It improves queue handling, player selection clarity, search behavior, Radio favorites, progress timing, and Diagnostics without adding new experimental features.

Why This Release Exists

The 5.9.2 hotfix restored Settings and Diagnostics access. After users could share better reports, the remaining issues were clearer:

• some queues were shown as empty or partial even when Music Assistant had a larger queue
• entity: did not always behave like the expected default player
• provider search could stop after library results or feel like it never searched Spotify/Music Assistant providers
• Radio favorite actions could still target the current item instead of the selected station
• users with duplicate player names needed to see the real entity id while pinning/selecting players
• progress could drift from Music Assistant timing in some setups

Fixed And Improved

• Improved queue snapshot handling so partial Music Assistant queue windows are detected instead of being treated as a clean success.
• Keeps fuller rendered queue data when a new queue API response is only a partial window.
• Improves Diagnostics wording for partial Queue snapshots so reports now show when Home Assistant/Music Assistant only returned part of the queue.
• Makes the configured entity act as a stable default player while still allowing query-string player overrides and currently playing players to take priority.
• Adds clearer player labels with entity ids in player-selection surfaces, helping users distinguish duplicate friendly names.
• Fixes provider search flow so HOMEii can show fast library results first and still continue provider/direct Music Assistant search in the background.
• Adds Direct Music Assistant music/search provider search support using the current Music Assistant search command shape.
• Fixes search result replacement so provider results can merge in after library results instead of being discarded.
• Fixes RadioBrowser/external radio favorites so they use local item favorites instead of the Music Assistant current-media favorite path.
• Keeps English/LTR search input alignment from leaking into RTL layouts and vice versa.
• Improves progress calculation so the player position remains closer to Music Assistant by preferring trusted player timing when queue timing drifts.

Diagnostics v7

Diagnostics now adds two focused checks:

• Configured entity: reports whether the configured card entity exists, whether it looks like a Music Assistant player, whether it is hidden by pinned/excluded filters, and why HOMEii selected another player if it did.
• Search providers: when run after a search, reports HA search availability, Direct music/search availability, result counts, and timing for fast/library search versus provider search.

Queue Diagnostics also reports partial queue windows more clearly, including cases where the rendered queue count is lower than the queue state count.

Important Notes

This release improves queue handling and diagnostics, but it does not claim that every empty Queue report is caused by HOMEii.

If Home Assistant or Music Assistant only returns a partial queue and no fuller Mass/Direct queue path is available, HOMEii cannot invent missing queue items. In that case, 5.9.3 should at least report the exact limitation clearly instead of showing a misleading OK state.

Spotify/provider search can still be slow when Music Assistant itself is waiting on a cold provider search. HOMEii now avoids stopping early after library results, but provider latency is still controlled by Music Assistant and the provider.

Validation

• node --check src/homeii-music-flow.js
• node --check src/core/base-music-card.js
• npm.cmd run build
• npm.cmd test
• Full Vitest suite passed locally: 231 tests.
• Production build and release artifact sync passed locally for 5.9.3.

Manual Resource Refresh

After updating, use a hard refresh or update the resource cache-buster:

/local/community/homeii-music-flow/homeii-music-flow.js?v=5.9.3

HOMEii Music Flow 5.9.2

HOMEii Music Flow 5.9.2

HOMEii Music Flow 5.9.2 is a small hotfix release for the in-card Settings screen.

Why This Release Exists

Some users could not open the in-card Settings screen and saw this error:

this._settingsSectionAnnouncements is not a function

That also blocked access to in-card Diagnostics, which made it harder to investigate the open empty-queue reports.

Fixed

• Fixed the in-card Settings crash caused by the missing Announcements settings section.
• Restored the Announcements section inside in-card Settings.
• Restored access to Music Assistant Diagnostics from the card Settings screen.
• Added regression coverage so the Settings screen must render Announcements and Diagnostics without throwing.
• Improved the setup message for users who configure ma_url / ma_token without the Home Assistant Music Assistant integration.

Important Note About Queue Reports

This release does not claim to fix the empty Queue issue.

It restores Diagnostics access so affected users can now provide the useful report:

1. Update to 5.9.2.
2. Open HOMEii Music Flow.
3. Open Settings inside the card.
4. Open the Music Assistant section.
5. Open Diagnostics.
6. Run Diagnostics while Music Assistant shows a queue but HOMEii shows an empty queue.
7. Copy and paste the full report into the GitHub issue.

Direct Music Assistant / Sendspin Clarification

ma_url and ma_token are for Direct Music Assistant access and Sendspin / This Device features.

They do not replace the Home Assistant Music Assistant integration. For the full card experience, Music Assistant should still be connected to Home Assistant and expose at least one Music Assistant media_player.

Validation

• node --check src/homeii-music-flow.js
• node --check dist/homeii-music-flow.js
• npm.cmd test -- tests/runtime-baseline.test.js tests/settings-accordion.test.js
• Production build and release artifact sync passed locally for 5.9.2.

Manual Resource Refresh

After updating, use a hard refresh or update the resource cache-buster:

/local/community/homeii-music-flow/homeii-music-flow.js?v=5.9.2

HOMEii Music Flow 5.9.1

HOMEii Music Flow 5.9.1

Release date: 2026-06-15

HOMEii Music Flow 5.9.1 is a focused stability and support release after 5.9.0. The main goal is simple: keep the proven Music Assistant playback path working, reduce confusing support loops, make group/player behavior clearer, and prepare the card for the upcoming HOMEii Flow Engine integration without forcing any new backend dependency yet.

Overview

5.9.1 is the release for real-world cleanup after the 5.9.0 rollout. It restores the 5.9.0 playback service path, improves queue and artwork diagnostics, makes group changes safer, adds Radio and favorites controls, clarifies pinned-player selection, lets users acknowledge repeated card warnings, and adds configurable screensaver Lyrics controls.

The release also includes optional HOMEii Flow Engine bridge infrastructure. That bridge is intentionally safe by default: existing dashboards continue to use the current Home Assistant and Music Assistant paths unless the future Engine integration is installed and enabled.

Highlights

• Playback stability: music_assistant.play_media remains the primary playback path, matching the behavior users already trusted in 5.9.0.
• Diagnostics v6: diagnostics now reports selected-player source, group state, queue UI/API mismatch, rendered artwork DOM health, authenticated artwork fallback, browser artwork loading, Direct Music Assistant, Sendspin readiness, and optional Engine bridge status.
• Safer group management: group screens show the master/owner clearly, keep all players visible, show pending add/remove changes, and separate Update Group from Disconnect All.
• Cleaner pinned-player setup: visual-editor pinned and excluded player selectors now show friendly names together with entity ids, reducing confusion when several players share a similar name.
• Repeated warning acknowledgement: repeated card issue messages can now be confirmed so the same warning does not keep looping, while new or changed issue text can still appear.
• Library and Radio control: favorites-only filtering, Radio source mode, and consistent List/Grid preference handling are included in the stable package.
• Screensaver Lyrics controls: when Screensaver controls are enabled, the visual editor can expose Lyrics, Sync lyrics, Smaller lyrics, and Larger lyrics buttons. The buttons stay in the same action row and use temporary pressed highlighting.
• Artwork resilience: cross-origin artwork handling now has direct browser loading and authenticated fallback paths for cases such as HTTPS, external URLs, and Nabu Casa access.
• Music Assistant 2.9 readiness: native recommendation hooks are available for HOMEii recommendations and Studio Mix flows when the direct MA API supports them.

Fixes And Improvements

Playback And Queue

• Restores the stable 5.9.0 music_assistant.play_media playback path.
• Keeps query-string player overrides without letting configured-player selection interfere with playback.
• Refreshes the selected queue before opening Queue Flow.
• Applies a valid queue snapshot back into the UI when queue APIs return data but the rendered queue is empty.
• Adds diagnostics for queue provider availability, queue UI state, and queue/render mismatches.

Groups

• Keeps the current master/owner visible in the group screen.
• Adds per-player group labels: Connected, Master, Tap to join, Will join, Will remove, and Disconnects all.
• Uses a diff-based group apply flow so removing one speaker does not clear the whole group.
• Avoids calling join again for removal-only changes.
• Waits for Home Assistant to confirm expected group state before showing success.
• Rebases member-selected group edits onto the actual group owner.
• Treats master removal as an intentional full-group disconnect, matching Home Assistant and Music Assistant behavior.
• Adds a main-player group volume shortcut when the selected player is part of a group.

Library, Favorites, And Radio

• Adds favorites-only filtering for mobile library pages.
• Keeps Radio favorites on a Music Assistant-only path so external RadioBrowser results do not mix with saved MA favorites.
• Adds Radio source mode: Combined, Music Assistant first, Music Assistant only, or RadioBrowser only.
• Honors Library List/Grid preference across library pages, search results, liked entries, and artist album sections.
• Fixes item-scoped favorite actions from search and menus so favorites are created for the selected item instead of depending on the currently playing media.

Screensaver And Lyrics

• Screensaver can automatically open Lyrics mode while music is playing and keep clock mode while idle.
• Closing Lyrics manually is respected per track so it does not immediately reopen for the same song.
• Optional visual-editor Screensaver buttons now include Lyrics, Sync lyrics, Smaller lyrics, and Larger lyrics.
• Lyrics sync and font-size buttons stay on the same row as the rest of the screensaver controls.
• Screensaver control buttons use temporary touch/click highlighting and return to transparent afterward.
• Wide and desktop Lyrics controls remain visible and scrollable when space is tight.

Diagnostics And Artwork

• Diagnostics v6 adds selected-player source, group service path, group owner, group members, queue UI state, artwork browser loading, authenticated artwork fetch fallback, and rendered artwork DOM checks.
• Cross-origin hydrated artwork uses direct browser image loading instead of a CORS-sensitive fetch blob path.
• Music Assistant imageproxy artwork can use authenticated fetch-to-blob loading when ma_token is configured.
• Diagnostics can now better distinguish missing artwork from browser access-path failures.

Configuration And Editor

• Adds a dedicated Screensaver section in the visual editor.
• Pinned and excluded player selectors show entity ids next to friendly names.
• Repeated card issue warnings can be acknowledged to prevent identical notification loops.
• Adds optional HOMEii Flow Engine bridge options:

homeii_engine_mode: auto
homeii_engine_timeout_ms: 3500
homeii_engine_instance_id: ""
homeii_engine_profile_id: ""

The Engine bridge is optional. auto keeps the card compatible with normal frontend-only operation.

What Is Not In 5.9.1

Some larger items are intentionally held for later releases:

• Full HOMEii Flow Engine integration release.
• Full alias-management UI.
• Crossfade controls.
• Lazy locale loading.

Those were kept out of 5.9.1 so this release can stay focused on stability and support fixes.

6.0.0 Teaser

5.9.1 quietly lays the track for HOMEii Music Flow 6.0.0.

The next major release is planned around the HOMEii Flow Engine integration: deeper backend awareness, richer diagnostics, smarter player state, queue/library proxying, grouping orchestration, scheduling, timers, statistics, volume rules, Sendspin status, and stronger recommendation flows. The goal for 6.0.0 is not just "more buttons"; it is a more intelligent music surface that understands the home behind the dashboard.

5.9.1 is the stable stepping stone. 6.0.0 is where the integration story starts to open up.

Validation

Before release, the following checks passed locally:

• Production build and release artifact sync for 5.9.1.
• Full ESLint.
• Full Vitest suite: 229 tests passed.
• node --check dist/homeii-music-flow.js.

Install / Cache Refresh

HACS users can update normally once the GitHub release is available.

Manual installs should replace the contents of:

/config/www/community/homeii-music-flow/

Then refresh the Dashboard resource with:

/local/community/homeii-music-flow/homeii-music-flow.js?v=5.9.1

After updating, hard refresh the Home Assistant dashboard or restart the HA Companion app if the old frontend bundle remains cached.

HOMEii Music Flow 5.9.0

HOMEii Music Flow 5.9.0

Release date: 2026-06-03

HOMEii Music Flow 5.9.0 is a major mobile, diagnostics, settings, and community release. It promotes the 5.8.2 beta stabilization work into a stable release, adds the new Library Wheel browsing experience, improves phone edge-to-edge behavior, expands Diagnostics v3, and incorporates several community PR ideas into the main card.

Release Highlights

• New Library Wheel experience: the Queue Wheel-style vertical browser is now available across the library: playlists, artists, albums, tracks, liked items, radio stations, and artist albums.
• Artist album wheel as a full-screen page: artist albums now open in a clean Queue Flow-style full page with its own close button. The caption shows the album title and release year.
• Radio wheel polish: Radio uses one stable wheel stage instead of stacking multiple sections. The caption shows the station name.
• Diagnostics v3 is now a headline support tool: diagnostics can be run from the in-card settings and the Home Assistant visual editor, with clearer checks for Music Assistant, queue/library providers, Direct API, Sendspin, browser context, artwork paths, and privacy-safe URLs.
• Phone edge-to-edge mode: phones can use a true full-screen card experience while menus open as frontmost full-screen layers instead of overlapping controls.
• Reusable dashboard support: card_id isolates per-card state, and query-string player overrides such as ?player=kitchen_sonos make reusable dashboard includes much easier.
• Settings and performance work: visual settings are organized into accordion sections, frequent toggles refresh without rebuilding the whole card, and artwork cache behavior adapts better to the selected performance profile.
• Danish localization: Danish is now included, with follow-up placeholder fixes so translated runtime variables render correctly.

New: Library Wheel

The Queue Wheel proved useful for fast queue navigation, so 5.9.0 extends the same interaction model into the music library.

Available wheel pages:

• Playlists
• Artists
• Albums
• Tracks
• Liked items
• Radio stations
• Artist albums

The goal is fast browsing on phones and touchscreens without turning library pages into cramped grids. The normal grid/list views remain available; the wheel is an additional browsing mode.

Artist albums and radio received extra polish after local testing:

• Artist album wheel opens as a dedicated full-screen page, not inside the artist detail section.
• Artist album captions show album title and year.
• Radio wheel renders one scroll stage only, avoiding long stacked pages.
• Radio captions show the station name.

Diagnostics v3

Diagnostics v3 is designed to reduce support loops and make Music Assistant setup issues easier to understand.

It reports:

• HOMEii runtime version and diagnostics version.
• Browser, platform, viewport, DPR, touch support, and language.
• Home Assistant URL details with privacy-safe redaction.
• Music Assistant service availability.
• Music Assistant config entry state.
• Strict Music Assistant players and fallback media players.
• Selected-player markers such as app_id, mass_player_type, active_queue, and registry platform.
• Direct Music Assistant API and WebSocket state when configured.
• Sendspin browser support and endpoint readiness.
• Queue identity, queue providers, queue snapshot status, and queue artwork sample.
• Library providers, library coverage, and library artwork sample.

External and private hostnames are redacted by default in visible and copied reports.

Mobile And Layout

5.9.0 includes several phone-focused fixes and improvements:

• Edge-to-edge mode is part of the phone layout mode choice.
• Compact-card expansion opens into a frontmost full-screen experience.
• Full-screen menus no longer layer controls on top of each other.
• The Actions screen behaves like a full-screen mobile page.
• Player-selection controls were moved higher in the phone layout for better spacing.
• The library toolbar keeps the wheel button compact so it does not overlap search, sort, player focus, or quick action buttons.
• The Players screen action hub is clearer, with four icon-and-text actions: This device, Queue, Groups, and Clear all.

Settings, State, And Reusable Dashboards

This release includes the community-driven card_id direction and reusable-dashboard work:

• Optional card_id YAML key scopes browser/local storage per card instance.
• Multiple cards in the same browser can keep different selected players, pinned/excluded players, themes, layout choices, screensaver settings, and other in-card customizations.
• Query-string player overrides are supported:

?player=kitchen_sonos
?homeii_player=kitchen_sonos
?homeii_player_<card_id>=kitchen_sonos

This makes it easier to reuse the same dashboard/card definition across rooms and tablets.

Migration note:

Adding card_id to a card that previously had no card_id will appear to reset that card's in-card customizations once. The old global values remain in browser storage; the card simply starts reading from card-scoped keys.

Music Assistant Compatibility

5.9.0 includes the full 5.8.2 beta stabilization series:

• Integration-first behavior so core card features can run through the Home Assistant Music Assistant integration.
• Clearer handling when Direct API browser access is blocked by CORS or mixed-content rules.
• Better fallback behavior when Music Assistant services exist but strict player markers are missing.
• More useful queue and library diagnostics.
• Correct config_entry_id handling for Home Assistant music_assistant service calls that require it.
• Cleaner music_assistant.get_queue diagnostic calls.
• Reduced retry noise for invalid direct Music Assistant URLs.
• Queue snapshot protection so an initial partial or empty Home Assistant response does not replace a complete queue.

Issue #28 remains a special compatibility case for setups where the selected player is exposed as a generic Home Assistant player without Music Assistant queue identity. Diagnostics v3 now gives enough context to keep investigating without blocking the stable release.

Fixes

• Fixes the beta 8 regression where starting a playlist could leave only one or two queue items visible.
• Fixes mobile visual-editor diagnostics fallback when clipboard access is blocked by the HA Companion app or browser.
• Fixes visual-editor diagnostic contrast in themes that made text too light.
• Keeps visual-editor player settings focused on strict Music Assistant players instead of every generic media_player.
• Fixes Danish interpolation placeholders such as {player}, {title}, {count}, and {remaining}.
• Keeps Direct API failures non-fatal when the Home Assistant Music Assistant integration is available.
• Improves radio and artist-album wheel scrolling so they behave like the Queue Wheel.

Community Credits

Huge thanks to @tocDK for taking an active role in this release cycle.

His PRs and proposals helped shape:

• card_id / per-card state isolation.
• Settings structure and refresh performance.
• Artwork cache behavior by performance profile.
• Danish localization.
• Danish placeholder fixes.
• Several practical performance and maintainability discussions.

Some PRs were not merged verbatim because this release needed to stabilize the current code path, but the ideas and fixes were incorporated into 5.9.0 with release credit.

Thank you also to everyone who opened issues, posted screenshots, ran beta builds, copied diagnostics reports, and helped find real-world mobile and Music Assistant edge cases. The 5.9.0 release is very much shaped by that feedback.

Validation

Before release, the following checks passed:

• Full ESLint.
• Full Vitest suite: 192 tests passed.
• Vite production build.
• Release artifact sync into dist/.

Install / Cache Refresh

HACS users can update normally once the GitHub release is available.

Manual installs should replace the contents of:

/config/www/community/homeii-music-flow/

Then refresh the Dashboard resource with:

/local/community/homeii-music-flow/homeii-music-flow.js?v=5.9.0

After updating, hard refresh the Home Assistant dashboard or restart the HA Companion app if the old frontend bundle remains cached.

HOMEii Music Flow 5.8.2-beta.7

HOMEii Music Flow 5.8.2-beta.7

This beta focuses on issue #28, Diagnostic v3, and a cleaner phone Queue Flow entry point.

Fixed

• Keeps the card usable through the Home Assistant Music Assistant integration when music_assistant services are available even if the config entry lookup reports not_loaded.
• Uses generic HA media_player entities as compatibility fallback targets only when Music Assistant services are exposed by Home Assistant.
• Treats browser-blocked Direct API failures such as CORS/preflight or Failed to fetch as optional Direct/Sendspin access-path warnings when the HA integration can still run core card features.
• Removes the invalid limit payload from the HA music_assistant.get_queue queue snapshot path.
• Removes the phone Queue Flow button above the artwork. Queue Flow remains available from Quick Actions.

Added

• Upgrades in-card and visual-editor diagnostics to Diagnostic v3.
• Adds integration signal reporting, strict/fallback player counts, selected-player marker details, queue provider checks, and library provider checks.
• Keeps privacy redaction for Home Assistant, Music Assistant, Sendspin, and artwork hostnames.

Testing Notes

After installing, hard refresh the Home Assistant dashboard and make sure the Lovelace resource URL/cache key is updated to:

/local/community/homeii-music-flow/homeii-music-flow.js?v=5.8.2-beta.7

For artwork/queue/library issues, open the card, go to Settings > General, set Settings Source to In-card Settings, then run Settings > Music Assistant > Diagnostics and paste the copied Diagnostic v3 report into the GitHub issue.

HOMEii Music Flow 5.8.1

HOMEii Flow 5.8.1

Release date: 2026-05-31

HOMEii Flow 5.8.1 is a focused hotfix on top of 5.8.0. It keeps the full 5.8.0 feature set and addresses the Music Assistant compatibility and artwork regressions reported after the upgrade.

Hotfix Highlights

• Restores Music Assistant 2.8.x player compatibility for setups where Home Assistant exposes MA players as normal media_player entities without the newer MA markers.
• Keeps HOMEii Flow strict when Music Assistant is actually missing, so unrelated Home Assistant media players are still not treated as a valid setup.
• Stops clearing the selected player queue manually before music_assistant.play_media, letting Music Assistant handle replace playback and reducing wrapper/artwork timing races.
• Falls back from invalid image-proxy IDs to legacy path/provider artwork URLs, which helps older Music Assistant payloads continue to show cover art.
• Keeps visual-editor player selectors usable in older MA/Home Assistant combinations.
• Prevents the card screensaver from opening while the card is being edited in the Home Assistant visual editor.

Why This Matters

5.8.0 tightened Music Assistant player detection and expanded artwork handling. That was correct for newer MA payloads, but too strict for some Music Assistant 2.8.x installations and too optimistic for some image-proxy payloads. 5.8.1 keeps the newer safeguards while adding compatibility paths for those real-world setups.

The playback change also removes an unnecessary queue-clear step before music_assistant.play_media. For replace playback, Music Assistant can handle the replacement itself, and avoiding the extra clear reduces the chance of player wrapper metadata being lost during fast browser-player transitions.

Validation

• Full Vitest suite passed.
• Vite production build passed.
• Full ESLint passed.
• Release artifacts were regenerated and synced into dist/.

Install / Cache Refresh

HACS users can update normally after the GitHub release is available.

Manual installs should replace the contents of:

/config/www/community/homeii-music-flow/

Then refresh the Dashboard resource with:

/local/community/homeii-music-flow/homeii-music-flow.js?v=5.8.1

5.8.1 includes all 5.8.0 features and fixes; the full 5.8.0 release overview remains in RELEASE_NOTES_5.8.0.md.

HOMEii Music Flow 5.8.0

HOMEii Flow 5.8.0

Release date: 2026-05-30

HOMEii Flow 5.8.0 is the next public release after 5.7.1. It includes the full set of project changes made since 5.7.1: architecture, mobile layout, artwork, queue, lyrics, library, Flow Assistant, visual editor, release tooling, and regression coverage.

This release is not just a small patch. It keeps the 5.7.1 foundation, then makes the card easier to maintain, more stable on real Home Assistant dashboards, and smoother on phones, wall tablets, and Section dashboards.

Why This Release Matters

5.8.0 is designed to make HOMEii Flow feel more dependable in the exact places where music dashboards usually feel fragile: narrow phone cards, wall-tablet dashboards, changing tracks from the queue, loading artwork from different Music Assistant payloads, opening lyrics while the screensaver is active, and searching large libraries from touch-first views.

The big user-facing story is simple: less jumping, less stale artwork, better layout control, richer browsing, and a more capable Flow Assistant. The big maintainer story is just as important: the runtime is now split into testable foundations so future releases can move faster without turning every change into a risky edit inside one huge file.

Highlights

• Major internal architecture refresh: the large card runtime has been split into focused core, config, state, media, layout, palette, players, and voice-matching modules.
• Better phone layout control: new phone layout modes let users choose Auto, Full, or Compact behavior instead of relying only on automatic sizing.
• Smarter compact experience: compact mode can auto-select a better widget shape, force compact/full layouts, and optionally open edge-to-edge or as a floating window.
• Artwork and now-playing reliability: queue artwork, image-proxy handling, artwork prefetching, and pending track transitions are much more stable.
• Lyrics in screensaver: lyrics can now move into the screensaver surface, including a configurable screensaver lyrics button.
• Library upgrades: library tab search, media detail views, artist/album detail handling, and visible loading feedback make browsing feel more complete.
• Flow Assistant matching improvements: Hebrew, Latin/English metadata, natural artist requests, playlist requests, and fallback search paths are handled more reliably.
• Release tooling and tests: package/source/dist version alignment, module cache-busting, runtime registration, and many foundation helpers now have regression coverage.
• Existing premium foundations stay intact: Hotel Mode, This Device / Sendspin, HTTPS Music Assistant external URL support, Control Room, announcements, ambient light sync, Night mode, timers, quick actions, auxiliary buttons, and multilingual/RTL support remain part of the 5.8.0 package.

Full Change Overview

5.8.0 includes all changes made after the public 5.7.1 release.

Architecture And Maintainability

• Splits the card runtime into reusable foundation modules instead of keeping all logic inside one giant file.
• Adds src/core/base-music-card.js as the shared base card runtime.
• Adds src/config/editor-forms.js for editor form schema generation.
• Adds src/config/editor-element.js for the visual editor custom element.
• Adds focused state modules for defaults, derived state, mobile settings, players, queue, favorites, and night mode.
• Adds focused media modules for artwork, now-playing state, media presentation, and media history.
• Adds focused layout and palette modules for responsive behavior and dynamic theme color handling.
• Adds src/core/voice-assistant-matching.js for Flow Assistant speech/query matching.
• Adds src/core/radio-browser-countries.js for shared RadioBrowser country labels and flags.
• Keeps existing variable names and behavior paths where possible while moving logic into smaller modules.
• Keeps the public custom card names and editor registrations intact.

Build, Packaging, And Release Flow

• Updates the packaged version to 5.8.0.
• Updates editor element version tags to the v580 generation.
• Updates build and release scripts so vite build runs before release artifact sync.
• Adds --preserve-main release behavior so the built/bundled main file is not accidentally overwritten during artifact sync.
• Copies src/core into dist/core during release artifact sync.
• Copies src/config into dist/config during release artifact sync.
• Adds versioned cache-busting imports for core, config, and localization modules.
• Keeps localization import URLs aligned with 5.8.0.
• Keeps the bundled dist/homeii-music-flow.js registerable as the primary HACS runtime file.
• Keeps Sendspin and vendor assets copied into the release package.

Runtime Baseline And Test Coverage

• Adds a runtime baseline test that verifies package, source, and dist versions stay aligned.
• Adds runtime registration coverage for the main card, mobile card, browser editor, and mobile editor.
• Adds visual editor shell coverage to confirm config updates are accepted.
• Adds dist runtime coverage to verify the bundled artifact can still be imported and registered.
• Adds foundation tests for editor forms, media artwork, now-playing state, RadioBrowser countries, responsive layout, palette handling, player logic, mobile settings, queue logic, favorites, and voice matching.
• Expands existing config validation tests for the new layout, compact, announcement, and screensaver options.

Phone Layout, Compact Mode, And Section Dashboards

• Adds mobile_layout_mode with Auto, Full, and Compact options.
• Adds in-card settings controls for Phone layout mode.
• Adds visual editor support for Phone layout mode.
• Adds Full phone mode for users who want the phone player to stay inline and request a taller dashboard slot.
• Adds forced Compact mode for users who want the card to stay as a compact tile.
• Keeps Auto mode as the adaptive default.
• Adds better automatic compact recommendations for narrow or short dashboard slots.
• Adds mobile_compact_edge_to_edge so compact expand can be edge-to-edge or a floating window.
• Adds in-card and visual-editor controls for compact edge-to-edge behavior.
• Improves compact popup class handling for edge-to-edge, floating-window, and tile states.
• Keeps Home Assistant navigation visible when compact edge-to-edge is disabled.
• Adds a smarter compact mini-widget recommendation for very narrow cards and short compact slots.
• Improves reserved Section dashboard height for compact tile and mini-widget layouts.
• Improves full-inline phone height handling for Section dashboards.
• Adds layout handling for short and tight phone heights so forced full layout can scroll instead of cutting controls.
• Improves tablet auto-fit and dense UI flags when night mode or up-next rows are active.
• Adds panel viewport fill detection for dashboard panels that are intended to use the full viewport height.
• Adds resize strategy helpers to avoid unnecessary heavy rebuilds during keyboard-like resizes and tablet stability mode.

Artwork, Images, And Dynamic Backgrounds

• Adds decoded artwork caching so images can render immediately after they have already been decoded.
• Adds immediate image src output for current artwork while decode is still pending.
• Adds high-priority artwork loading for current artwork.
• Adds artwork prefetch queue management with active request limiting.
• Prefetches current, next, previous, nearby, and visible queue artwork.
• Adds scroll-aware queue artwork prefetching for visible rows.
• Adds cache keys based on stable queue item identity and artwork identity.
• Improves Music Assistant image-proxy handling for /imageproxy, imageproxy?, and imageproxy/<id> paths.
• Adds normalized image-proxy size handling.
• Adds support for Music Assistant image proxy IDs.
• Adds support for base64 encoded local image payloads.
• Adds support for more artwork fields, including thumbnails, covers, media images, local images, preview images, external images, media item images, album images, and nested metadata images.
• Improves fallback artwork selection across player artwork, queue artwork, album artwork, media metadata, and provider metadata.
• Keeps queue artwork and player artwork from mixing when the queue item no longer matches the player-reported track.
• Changes important artwork surfaces to object-fit: contain where cropping caused user-visible problems.
• Adds background crossfade helpers for current artwork backgrounds.
• Keeps artwork backgrounds synchronized with dynamic theme updates.

Now Playing And Queue Reliability

• Adds pending queue play state that records the selected item key, URI, queue index, and target player.
• Keeps title, artist, album, URI, and artwork atomic during pending queue transitions.
• Prevents the phone now-playing surface from showing the new title with the old artwork during track changes.
• Locks the selected player while a queue play transition is pending, so another active player does not steal focus.
• Clears pending queue play state once the player and queue catch up.
• Adds stronger queue item identity helpers for stable IDs, playback IDs, URIs, and sortable indexes.
• Exports queue comparison helpers for test coverage and shared runtime use.
• Improves queue item matching by title, artist, URI, sort index, and stable item IDs.
• Adds queue mutation pending state so optimistic reorder/mutation flows do not fight immediate server refreshes.
• Improves playback duration handling, including string durations, ISO durations, and millisecond durations.
• Improves playback timestamp parsing across browser/server formats.
• Keeps mobile up-next and now-playing display sources more consistent with the Music Assistant queue snapshot.

Lyrics And Screensaver

• Adds a lyrics option to configurable screensaver control buttons.
• Adds a screensaver l...

HOMEii Music Flow 5.7.1

HOMEii Flow 5.7.1

Release date: 2026-05-26

HOMEii Flow 5.7.1 is a polish, safety, and hospitality release for the 5.7.x cycle. It keeps the large 5.7.0 foundation and focuses on the real-world dashboard details that came up during local testing: Hotel Mode, safer player priority, HTTPS Music Assistant access, Sendspin / Media Session sync, grouped-player feedback, Discover/library fixes, and phone/tablet visual polish.

Highlights

• Hotel Mode: a clean shared-space interface for guests, family dashboards, hotels, and wall tablets.
• Safer front player selection: temporary manual selection, front pinning, currently playing players, and defaults now resolve more predictably.
• HTTPS Music Assistant support: music_assistant_external_url lets HTTPS Home Assistant dashboards connect to an HTTPS-accessible Music Assistant endpoint for Sendspin/browser player use.
• Merged community PRs: PR #34, PR #35, and PR #36 from jingle-jew keep Sendspin / Media Session state active and synced while the screensaver is open, and add a macOS native Home Assistant WebView audio fallback.
• Italian localization: PR #37 from Dieghito72 adds Italian to the bundled language package.
• Grouping feedback: group join/disconnect actions now show loading feedback and clear stale group-volume state more reliably.
• Tablet and phone polish: recommendation drawer behavior, tablet mute sizing, pin placement, Discover layout, and screensaver transitions were refined.

Full Change Overview

5.7.1 closes the local 5.7.x polish cycle with a long list of practical fixes:

• Adds Hotel Mode for protected shared dashboards.
• Renames the user-facing Hebrew wording to "מצב מלון" instead of guest mode.
• Removes all main navigation items in Hotel Mode.
• Keeps the HOMEII FLOW logo visible in Hotel Mode.
• Keeps Hotel Mode focused on player controls, volume, search, artwork browsing, and player selection only.
• Hides queue transfer, grouping tools, advanced actions, long-press actions, theme toggle, media-source badges, and secondary controls in Hotel Mode.
• Restores the original search-button placement and sizing.
• Reduces duplicate artwork/background layers in Hotel Mode.
• Adds front-player priority so an actively playing player can appear first instead of always falling back to the first configured player.
• Adds front-player pinning, with pin priority above playing/default player selection.
• Keeps manual player selection possible even when another player is pinned or playing.
• Keeps manual inactive-player selection temporary, then returns to the pinned/playing/default hierarchy.
• Clears temporary manual selection when leaving and returning to the dashboard page.
• Fixes the phone case where manual player selection could immediately jump back to the pinned player.
• Refines player-card pin sizing, color, and top-corner placement.
• Removes the pin from queue-transfer player selection.
• Adds music_assistant_external_url for HTTPS-accessible Music Assistant connections.
• Keeps local ma_url for normal LAN/HTTP dashboards.
• Shows clear mixed-content/setup errors instead of trying to bypass browser security rules.
• Routes remote artwork through Music Assistant image-proxy paths where possible.
• Restores RadioBrowser station visibility in the library.
• Improves radio artwork fallback behavior.
• Removes the experimental Crossfade control because service support was not reliable enough.
• Adds group join/disconnect loading feedback.
• Adds separate connect/disconnect animation states for group actions.
• Fixes group disconnect so stale shared group volume clears without leaving and reopening the page.
• Makes group add/remove controls clearer, including selected-state feedback.
• Improves spacing and premium styling of group connect/disconnect buttons.
• Changes FLOW multi-player behavior so selecting more than one player starts a join/group flow instead of trying to play separately on each player.
• Fixes "Clean all" so stopped/cleared players also lose stale local artwork.
• Keeps Discover open when switching players on tablet.
• Moves the Discover style selector into the active-player area on tablet.
• Adds grid/list controls to the tablet Liked screen.
• Restores the mobile recommendation drawer button behavior from 5.7.0.
• Keeps the tablet recommendation drawer as a subtle fixed edge arrow.
• Fixes the mobile recommendation drawer action so it keeps the same glass-button styling as the other quick actions.
• Restores the 5.7.0 magic-wand icon after testing custom variants.
• Refines the music-library icon treatment.
• Shrinks tablet mute controls and trims heavy volume rows.
• Moves tablet quality/library/provider badges closer to the artwork so they feel less detached.
• Adds smooth fade-in and fade-out transitions when entering and leaving the screensaver.
• Keeps Sendspin / Media Session state active and synced while the screensaver is open.
• Adds a macOS native Home Assistant app fallback for Sendspin audio output.
• Adds Italian localization and keeps all language dictionaries aligned.
• Updates release packaging, cache-busting, tests, docs, and publishing notes for 5.7.1.

Hotel Mode

Enable with:

type: custom:homeii-music-flow
hotel_mode: true

Hotel Mode is designed for dashboards where the user should be able to play music, change volume, search, and switch players without touching advanced controls.

Included behavior:

• Main navigation items are removed.
• Queue management, advanced settings, group join/disconnect, queue transfer, long-press actions, theme toggle, source badges, and secondary actions are hidden.
• Core controls stay available: play/pause, previous/next, shuffle, repeat, volume slider, volume +/- buttons, search, player selection, and artwork browsing.
• Player selection remains simple and does not expose group/transfer actions.
• HOMEII FLOW branding is restored.
• Glassmorphism and aura lighting remain, but duplicate artwork layers are reduced for a cleaner premium look.

Player Priority And Pinning

5.7.1 improves how HOMEii Flow decides which player should be shown in front:

• Temporary manual player selection works even if another player is pinned or playing.
• A pinned front player remains respected once the short manual selection window ends.
• A currently playing player is preferred over inactive/default players when no temporary selection or pin is active.
• Temporary manual selection is cleared when leaving and returning to the dashboard page.
• The player-card front pin is smaller, better positioned, and uses a quiet grey inactive state with cover-accent active color.

Music Assistant, HTTPS, And Sendspin

New optional config:

type: custom:homeii-music-flow
ma_url: "http://LOCAL_MUSIC_ASSISTANT:8095"
music_assistant_external_url: "https://YOUR_HTTPS_MA_URL"

Behavior:

• HTTP/LAN dashboards keep using ma_url.
• HTTPS Home Assistant dashboards can use music_assistant_external_url for Sendspin websocket/browser-player connections.
• Browser mixed-content rules are respected. If Home Assistant is served over HTTPS and only insecure Music Assistant access is configured, HOMEii Flow shows an explicit error instead of trying to bypass the browser.
• Remote artwork is routed through Music Assistant image proxy paths when possible, reducing CORS failures in search, library, and radio views.
• Sendspin falls back to direct AudioContext output in macOS native Home Assistant WebView when MediaStreamDestination is unavailable.

Grouping, FLOW, Discover, And Library

• Group join and disconnect actions now show loading/working feedback.
• Disconnecting a group clears stale shared group volume state without needing to leave and re-open the page.
• The group player picker is visually cleaner and aligns controls better with the player card corners.
• Queue-transfer player selection no longer shows the front-pin control.
• FLOW now treats selecting more than one player as a join/group scenario rather than attempting separate playback on each selected player.
• "Clean all" clears stale local artwork after stopping/disconnecting players.
• Discover stays open when switching players on tablet.
• Discover style selection sits with the active-player area on tablet.
• RadioBrowser stations are visible again in the library flow.
• The tablet Liked screen has grid/list controls.

UI Polish

• Restores the 5.7.0 magic-wand icon.
• Restores the 5.7.0 mobile recommendation drawer button behavior in the quick-action row.
• Keeps the tablet recommendation drawer as a subtle edge arrow.
• Shrinks tablet mute controls and their internal icon.
• Refines player-card pin placement, group add/remove controls, group action buttons, and volume rows.
• Adds smooth fade-in and fade-out transitions for the screensaver.
• Removes the experimental Crossfade control for now because service support was not reliable enough for release.

Contributors

Special thanks to jingle-jew / Julien Moreau B. for the excellent work, careful testing, and repeated PRs that made this release better:

• PR #34
• PR #35
• PR #36
• Sendspin / Media Session improvements
• macOS native Home Assistant WebView audio fallback
• French wording work
• Testing and feedback during the 5.7.x polish cycle
• The kind of practical, real-device fixes that make HOMEii Flow more reliable for everyone

Thanks also to the localization contributors whose work remains part of the release:

• Daniel Eduardo Gonzalez (@danielxb-ar) for Spanish.
• Donatas / donatassmarterhome for Lithuanian.
• Julien Moreau B. / jingle-jew for French.
• @Dieghito72 for Italian.
• @gao19970120 for Simplified Chinese.

Validation

Relea...

HOMEii Flow 5.7.0

HOMEii Flow 5.7.0

HOMEii Flow 5.7.0 is the biggest release so far: a major community-driven update focused on Compact and Mini player modes, Home Assistant Section dashboard support, weak-device performance, Music Assistant safety, player/group reliability, screensaver polish, discovery improvements, and new community translations.

This release was shaped by real user feedback, screenshots, bug reports, and feature requests. Thank you to everyone who tested, reported issues, and asked for improvements. I tried to respond to almost every practical request and turn it into a better daily music experience without losing the premium feel of the card.

Major Highlights

• Rebuilt the Compact card for real Home Assistant dashboards.
• Added a new Mini player mode for small mobile/Section layouts.
• Added stronger performance profiles for weak devices: Full, High, Low, and Ultra Lite.
• Enforced Music Assistant-only player safety. The card no longer falls back to unrelated Home Assistant media players.
• Improved Home Assistant Section dashboard behavior, sizing, stacking, popup handling, and manual height support.
• Expanded screensaver controls and made screensaver surfaces more flexible and performance-aware.
• Added a much larger FLOW and Discover style catalog, closer to familiar Spotify-style genre/mood choices.
• Added Spanish, French, and Lithuanian translations.

Compact And Mini Player

• The Compact card now behaves correctly beside other Home Assistant cards.
• Fixed compact cards stacking above or below unrelated Section dashboard cards.
• Compact full-screen now opens as a true popup-style surface instead of resizing the card in place.
• Fixed clicks passing through the compact full-screen popup to the dashboard underneath.
• Fixed compact full-screen controls where only the close button responded.
• Improved compact mobile and tablet proportions.
• Improved compact album art sizing and cover browsing.
• Cover browsing selections in compact mode can now start playback.
• Replaced the old triangle expand button with a clearer full-screen icon.
• Added active-player access to the Mini card header.
• Added the new Mini two-row player mode for mobile dashboards where the regular compact card still takes too much space.
• Mini mode keeps artwork, title, artist, previous/play/next, volume controls, active-player access, and full-screen expansion in a smaller premium widget.

Performance Optimization

• Added clearer performance profiles: Full, High, Low, and Ultra Lite.
• Ultra Lite is designed for weak tablets, wall panels, older browsers, and low-power kiosk devices.
• Ultra Lite reduces expensive effects such as heavy blur, transparency, background motion, animation, dynamic visuals, and screensaver motion.
• Core controls remain available even in the lightest mode.
• Screensaver and opened panels now respect performance mode more carefully.
• Menus and panels use less transparency in Ultra Lite to reduce rendering cost.
• The goal is simple: keep HOMEii Flow usable on weaker devices without making it feel broken or stripped of its music experience.

Music Assistant Safety

• HOMEii Flow now requires valid Music Assistant players.
• If Music Assistant is missing, inactive, unavailable, or exposes no supported players, the card shows a clear setup message.
• The card no longer fills the player list with unrelated Home Assistant media players.
• This avoids accidental control of devices that do not belong to Music Assistant.
• Player exclusion is available from the visual editor.
• Player sorting can be alphabetical or custom.
• Custom player-order rows now match the real number of available players instead of showing a fixed long list.

Players, Groups, And Queue Transfer

• Improved active-player selector behavior across compact, mini, full, screensaver, and opened surfaces.
• Hardened group join, disconnect, queue transfer, stop, and clear flows.
• Improved behavior with newer Music Assistant beta versions and unsupported or idle devices.
• Reduced false success/error feedback when grouping or disconnecting speakers.
• Improved player group UI cards, selected state, and volume controls.
• Improved transfer queue and group control surfaces.

Quick Actions And Auxiliary Buttons

• Home was moved into the Quick Actions row.
• Home is now available even when the player is idle.
• Added Quick Action ordering in the visual editor.
• Fixed Quick Actions disappearing after playback starts and only returning after a page refresh.
• Irrelevant Quick Actions are hidden from the idle player view.
• Added multiple auxiliary buttons.
• Auxiliary buttons can use configurable names, Home Assistant icons, and actions.
• Added a dedicated search Quick Action that opens a clean search-only popup.
• Improved action menu tile sizing so labels and icons do not clip.
• Quick Actions can wrap into two rows on constrained layouts to preserve artwork space.

Media Controls And Volume

• Improved immediate feedback for play, pause, shuffle, repeat, previous, next, mute, and volume.
• Added optional plus/minus volume buttons.
• Volume step is configurable from 1% to 10%, with 5% as the default.
• Fixed plus/minus volume changing from the wrong baseline.
• Fixed volume slider and percentage not updating immediately after choosing a preset.
• Fixed compact volume preset popup appearing under other cards.
• Enlarged and balanced media-control icons.
• Improved shuffle and repeat visuals.
• Repeat badge now sits outside the icon center so it does not block the icon.
• Shuffle active state now uses border/glow styling instead of a dot that covers the icon.
• Tuned tablet media controls.
• Reduced mute button size.

Screensaver

• Added configurable screensaver button visibility.
• Screensaver buttons can include Flow Assistant, previous, next, play/pause, power, mute, and like.
• Flow Assistant now opens above the screensaver.
• Flow Assistant no longer exits the screensaver unintentionally.
• Removed the experimental screensaver_kiosk_mode option because it did not provide a useful difference in Home Assistant chrome behavior.
• Screensaver can use a full-page surface similar to compact full-screen mode.
• Added gentle idle animation for no-content screens and idle players.
• Dynamic artwork color and ambient-light behavior continue updating during screensaver playback where Home Assistant/browser visibility allows it.
• Reduced screensaver motion and visual cost in Ultra Lite mode.

FLOW, Discover, Library, Search, Queue, And Lyrics

• Replaced fixed FLOW categories with a much larger familiar style catalog.
• Applied the expanded style catalog to Discover.
• Discover recommendations are less repetitive between opens.
• Discover can show the active player.
• Adjusted Discover recommendation orbs on narrow screens so they do not overlap.
• Added default library view setting: Grid or List.
• Manual Grid/List switching is still available inside library pages.
• Added grid mode inside playlist and album drill-in views.
• Improved library navigation to avoid unexpected returns to the main page.
• Added History play-all.
• Added like support to queue row actions.
• Queue like action now gives clearer feedback.
• Queue row actions were repositioned so like does not trigger row playback accidentally.
• Redesigned the lyrics panel with a more polished dynamic background, clearer typography, and better alignment across devices.
• Expanded Studio panels and media sheets so they use more of the screen instead of feeling like half-height panels.

Flow Assistant

• Added response/open-time limits so assistant panels do not remain active too long.
• Fixed assistant dialogs opening behind the screensaver.
• Fixed screensaver Flow Assistant so it opens over the current screensaver without exiting it.
• Fixed an empty Menu overlay that could cover the correct player selector after a rebuild.

Localization

New languages are now bundled:

• Spanish
• French
• Lithuanian

Thank you to the community translators and contributors:

• Daniel Eduardo Gonzalez (@danielxb-ar) for Spanish.
• Donatas / donatassmarterhome for Lithuanian.
• Julien Moreau Brousseau for the French translation work.
• Jingle Jew for French wording corrections.
• @gao19970120 for the Simplified Chinese contribution.

Also fixed French language selection staying in English after choosing French in the editor.

Bug Fixes

• Fixed the library loading spinner loop reported in issue #19.
• Fixed the fixed-height/tablet Section dashboard regression reported in issue #17.
• Improved manual height handling.
• Fixed delayed media-control response and missing immediate UI feedback.
• Fixed idle player view missing the Home action.
• Fixed idle recommendations changing too aggressively while the idle page is open.
• Fixed overlapping elements in media/action menus and opened screens.
• Fixed broken-looking small icons, including the library icon treatment.
• Fixed tablet and mobile intermediate layouts losing access to controls.
• Fixed compact popup sizing on phones.
• Fixed player selector from Mini/compact opening the wrong tiny surface before the real selector.
• Fixed volume dropdown/preset z-index from compact cards.
• Fixed screensaver Flow Assistant panel layering.
• Fixed Quick Action state mismatches after playback starts.
• Fixed French localization registration and release packaging.
• Fixed release localization cache busting for the expanded language package.

Upgrade Notes

• HACS users can update normally through HACS.
• Manual install users should copy the full dist/ folder and update the Dashboard resource query to:

/local/community/homeii-music-flow/homeii-mu...

5.6.1

5.6.1 - 2026-05-20

Release packaging hotfix for the Simplified Chinese language option.

• Fixes the visual-editor language dropdown not showing 简体中文 / Simplified Chinese for some users after installing 5.6.0.
• Root cause: the Chinese dictionary and LANGUAGE_OPTIONS were present in the release, but the main card imported ./localization/index.js without a version query, so Home Assistant/browser cache could keep the older language-options module.
• Adds release-time cache-busting to the packaged dist/homeii-music-flow.js localization import and to the dictionary imports inside dist/localization/index.js.
• Keeps runtime behavior otherwise unchanged from 5.6.0.