Yet Another Media Player (YAMP)

YAMP uses a dual-engine approach to resolve dynamic values in configuration fields. When a field is configured with a template, the engine determines the type based on the syntax used:

1. JavaScript Templates: Identified by the [[[ ... ]]] syntax. These are evaluated client-side via _evaluateJsTemplate and the result is stored in a resolve cache.
2. Jinja2 Templates: Identified by {{ ... }} or {% ... %} markers. These are resolved by subscribing to the Home Assistant render_template WebSocket service. The card updates when the server-side template value changes.

Once resolved, the value is cached and the card re-renders with the new data.

YAMP supports two distinct template engines for dynamic configuration. Both syntaxes have access to standard Home Assistant template functions (like states(), is_state()) and YAMP-specific variables.

1. Jinja2 (Server-Side): Uses standard Home Assistant syntax {{ ... }} or {% ... %}. It is evaluated on the Home Assistant backend and requires an active WebSocket connection. It has access to the full Home Assistant state machine.
2. JavaScript (Client-Side): Evaluated directly in your browser using triple brackets [[[ ... ]]]. This is extremely fast and ideal for restricted devices (like older iPads) where backend WebSocket template subscriptions might be blocked.

YAMP follows a specific priority and validation logic to ensure metadata accuracy:

1. Preferred Source: If prefer_ma_metadata is enabled, the card prioritizes metadata (title, artist, artwork) from the linked Music Assistant entity.
2. Fallback Validation: If falling back from a preferred source to the physical playback entity, the media_title must match exactly. If the titles differ, the fallback is blocked to prevent displaying stale or incorrect artwork.
3. Idle State: If show_idle_artwork_when_not_playing is set to true, the card will display the configured idle artwork for a specific chip when its associated entity is not actively playing.

By installing the mass_queue community integration (droans/mass_queue), YAMP unlocks advanced queue management features within the Search sheet.

Enabled Features:

• Queue Browsing: Fetching the upcoming queue and browsing playlist tracks.
• Queue Reordering: Drag-and-drop reordering of items in the upcoming queue list. YAMP optimizes the movement by calculating the most efficient sequence of move_up, move_down, or move_next calls.
• Queue Management: Moving items (up, down, next) and removing items from the queue.
• Playlist Management: Enables the Add to Playlist action in search results (automatically filters for editable playlists).

You can keep two YAMP instances in sync (e.g., a main card and a dedicated search card) by using an input_text helper and two specific action types:

1. sync_selected_entity: Writes the currently selected entity ID to the helper. Set in_menu: hidden so it runs in the background.
2. select_entity: Monitors the helper and automatically switches the card's active chip to match the helper's value.

Both actions require sync_entity_helper and sync_entity_type: yamp_playback_entity.

# On both cards:
actions:
  - action: sync_selected_entity
    in_menu: hidden
    sync_entity_type: yamp_playback_entity
    sync_entity_helper: input_text.current_yamp_entity
  - action: select_entity
    in_menu: hidden
    sync_entity_type: yamp_playback_entity
    sync_entity_helper: input_text.current_yamp_entity

If entities are compatible, you can group them via the hamburger menu using "Group Players".

• Grouped entities: Volume increases/decreases proportionately with the main entity.
• Individual control: Use the Grouped Players menu to adjust individual player volumes or sync the group volume to the main entity.
• Quick Grouping Mode: Double-click any entity chip to enter this mode.
  • Star Icon: Indicates the master player.
  • Plus (+): Join the active group.
  • Minus (-): Remove from the active group.
  • Exit: Double-click/tap any chip again.
• Persistence: Use always_show_quick_group: true to keep this mode active by default.

When extending or working with YAMP, follow these core rules:

• Dual-Engine Support: Any field that supports templating must be able to handle both Jinja2 ({{, {%) and JavaScript ([[[) markers.
• Editor Visibility: In the configuration editor, if a setting is unavailable due to a conflicting option, it should be rendered as disabled (.disabled=${true}) rather than being hidden from the user.
• Search Consistency: All search result items should be rendered using the renderSearchResultItem method in src/search-sheet.js to ensure a consistent look and feel across different search contexts.

When searching, you can access enqueue strategies via the 3-dot menu (dots-vertical) on any search result:

• Replace: Clears the current queue and plays the selection immediately.
• Next: Adds the selection to the queue immediately after the currently playing track.
• Replace Next: Replaces all upcoming items in the queue with the selection, starting after the current track.
• Add to Queue: Adds the selection to the very end of the queue.

If the built-in adaptive text doesn't meet your needs, you can use card-mod to apply custom CSS.

To increase font size for the details row (for cards shorter than 300px), target the .details class. To style the lyrics view, use the provided CSS variables.

card_mod:
  style: |
    .details {
      font-size: 2.4em !important;
    }
    .details .title {
      font-size: 1.6em !important;
    }
    .details .artist {
      font-size: 1.2em !important;
    }