### Install Project Dependencies

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Run this command in the project root to install necessary dependencies before making code changes. Use `npm ci` for an exact lockfile synchronization.

```bash
npm install
```

```bash
npm ci
```

--------------------------------

### Comprehensive YAMP Configuration Example

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

A detailed YAMP configuration showcasing a wide array of features, including entity synchronization, volume grouping, Music Assistant integration, artwork overrides, and custom actions. This example serves as a template for advanced setups.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.living_room_apple_tv
    name: Living Room
    volume_entity: media_player.living_room_sonos
    follow_active_volume: true
    music_assistant_entity: media_player.living_room_homepod
    group_volume: false
    sync_power: true
    hidden_controls:
      - favorite
      - shuffle
    hidden_filter_chips:
      - artist
      - podcast
  - entity_id: media_player.office_homepod
    name: Office
    group_volume: true
    music_assistant_entity: media_player.office_homepod_2
  - media_player.kitchen_speaker
  - media_player.entryway_display
search_results_limit: 50
search_results_sort: timestamp_added_desc
match_theme: true
show_chip_row: in_menu
alternate_progress_bar: true
adaptive_controls: true
control_layout: modern
swap_pause_for_stop: true
adaptive_text:
  - details
  - action_chips
hide_active_entity_label: true
card_height: 420
artwork_object_fit: contain
extend_artwork: true
media_artwork_overrides:
  - media_title: The Daily
    image_url: /local/podcasts/daily.png
    size_percentage: 85
  - missing_art_url: /local/artwork/default.png
idle_image: camera.family_slideshow
idle_timeout_ms: 30000
collapse_on_idle: true
always_collapsed: true
expand_on_search: true
hide_menu_player: false
idle_screen: search-next-up
actions:
  - name: Transfer Queue
    transfer_queue: true
    in_menu: false
  - name: Search Queue
    icon: mdi:magnify
    menu_item: search-next-up
  - name: Soul
    icon: mdi:music
    service: music_assistant.play_media
    service_data:
      entity_id: current
      media_id: apple_music://playlist/pl.23r98u32pqorijwaelkn
      enqueue: replace
    in_menu: true
  - name: Set the Mood
    icon: mdi:lightbulb-on
    service: script.set_mood
    script_variable: true
  - name: Player Docs
    icon: mdi:open-in-new
    action: navigate
    navigation_path: https://example.com/docs
    navigation_new_tab: true
```

--------------------------------

### Example Home Assistant Script for Setting Mood

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

This script demonstrates how to define fields for receiving variables and sequences actions, including playing media.

```yaml
alias: set_mood
mode: single
fields:
  yamp_entity:
    description: Target media player (MA entity if configured, else main entity)
  yamp_main_entity:
    description: Main configured entity
  yamp_playback_entity:
    description: Currently active playback entity
sequence:
  - action: light.turn_off
    metadata: {}
    data: {}
    target:
      entity_id: light.bedroom
  - action: switch.turn_on
    metadata: {}
    data: {}
    target:
      entity_id: switch.fireplace
  - service: music_assistant.play_media
    data:
      entity_id: "{{ yamp_entity }}"
      media_id: apple_music://track/1445094678
      enqueue: replace
```

--------------------------------

### Full Yet Another Media Player Configuration Example

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

A comprehensive YAML configuration demonstrating all available options for Yet Another Media Player, including entity settings, playback controls, artwork overrides, and custom actions.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.living_room_apple_tv
    name: Living Room
    volume_entity: media_player.living_room_sonos
    follow_active_volume: true
    music_assistant_entity: media_player.living_room_homepod
    group_volume: false
    sync_power: true
    hidden_controls:
      - favorite
      - shuffle
    hidden_filter_chips:
      - artist
      - podcast
  - entity_id: media_player.office_homepod
    name: Office
    group_volume: true
    music_assistant_entity: media_player.office_homepod_2
  - media_player.kitchen_speaker
  - media_player.entryway_display
search_results_limit: 50
search_results_sort: title_asc
match_theme: true
show_chip_row: in_menu
alternate_progress_bar: true
adaptive_controls: true
control_layout: modern
swap_pause_for_stop: true
adaptive_text:
  - details
  - action_chips
hide_active_entity_label: true
card_height: 420
artwork_object_fit: contain
extend_artwork: true
media_artwork_overrides:
  - title: The Daily
    image_url: /local/podcasts/daily.png
    size_percentage: 85
  - missing_art_url: /local/artwork/default.png
idle_image: camera.family_slideshow
idle_timeout_ms: 30000
collapse_on_idle: true
always_collapsed: true
expand_on_search: true
hide_menu_player: false  
idle_screen: search-next-up
actions:
  - name: Transfer Queue
    transfer_queue: true
    in_menu: false
  - name: Search Queue
    icon: mdi:magnify
    menu_item: search-next-up
  - name: Soul
    icon: mdi:music
    service: music_assistant.play_media
    service_data:
      entity_id: current
      media_id: apple_music://playlist/pl.23r98u32pqorijwaelkn
      enqueue: replace
    in_menu: true
  - name: Set the Mood
    icon: mdi:lightbulb-on
    service: script.set_mood
    script_variable: true
  - name: Player Docs
    icon: mdi:open-in-new
    action: navigate
    navigation_path: https://example.com/docs
    navigation_new_tab: true
```

--------------------------------

### YAML Configuration for Radio Station Playback Action

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

An example action to play a radio station, including metadata like title, subtitle, and an image URL, suitable for Chromecast devices.

```yaml
- name: 🎷 Jazz
  service: media_player.play_media
  service_data:
    entity_id: current
    media_content_id: https://streaming.live365.com/a49833
    media_content_type: music
    extra:
      metadata:
        metadataType: 3
        title: KJazz 88.1
        subtitle: KJazz 88.1
        images:
          - url: https://cdn-profiles.tunein.com/s37062/images/logod.jpg
```

--------------------------------

### Gesture-Only Card Configuration

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Configure a minimal card that hides all playback controls, relying solely on taps and swipes for interaction. This setup is ideal for a clean interface where gestures are preferred over visible buttons.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.office_homepod
    name: Office
    hidden_controls:
      - previous
      - play_pause
      - stop
      - next
      - shuffle
      - repeat
      - favorite
      - power
show_chip_row: in_menu
actions:
  - service: media_player.media_play_pause
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: tap
    name: Play/Pause
  - in_menu: hidden
    card_trigger: hold
    name: Volume Down
    service: media_player.volume_down
    service_data:
      entity_id: current
  - in_menu: hidden
    card_trigger: double_tap
    service: media_player.volume_up
    service_data:
      entity_id: current
    name: Volume Up
  - service: media_player.media_next_track
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: swipe_left
    name: Next Track
  - service: media_player.media_previous_track
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: swipe_right
    name: Previous Track
alternate_progress_bar: true
volume_mode: hidden
```

--------------------------------

### Gesture Triggers: Tap and Hold Actions

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Assign actions to card-level gestures on the artwork area. This example configures 'more-info' for a tap and 'search' for a hold, both hidden from the menu.

```yaml
actions:
  - icon: mdi:information
    menu_item: more-info
    in_menu: hidden
    card_trigger: tap
  - icon: mdi:magnify
    menu_item: search
    in_menu: hidden
    card_trigger: hold
```

--------------------------------

### Expand Card on Search Example

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Configure the card to temporarily expand to its normal size when the search interface is open, using `expand_on_search: true` with `always_collapsed: true`.

```yaml
type: custom:yet-another-media-player
entities:
  - media_player.living_room_apple_tv
  - media_player.kitchen_homepod
actions:
  - icon: mdi:magnify
    menu_item: search
always_collapsed: true
expand_on_search: true
```

--------------------------------

### Dynamic Navigation: Search IMDb for Current Title

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Use Jinja templates in `navigation_path` to create dynamic URLs. This example searches IMDb for the currently playing media title.

```yaml
actions:
  - name: IMDb
    icon: mdi:movie-search
    action: navigate
    navigation_path: 'https://www.imdb.com/find/?q={{ state_attr(current, "media_title") }}'
    navigation_new_tab: true
```

--------------------------------

### Dynamic Navigation: Search Genius for Lyrics

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Dynamically generate URLs using Jinja templates for external sites. This example searches Genius for lyrics based on the current media title and artist.

```yaml
actions:
  - name: Lyrics
    icon: mdi:music-clef-treble
    action: navigate
    navigation_path: 'https://genius.com/search?q={{ state_attr(current, "media_title") }} {{ state_attr(current, "media_artist") }}'
    navigation_new_tab: true
```

--------------------------------

### Disable Auto-Select for an Entity

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Prevent the card from automatically selecting an entity when it starts playing or becomes a master of a group by setting `disable_auto_select: true`.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.example
    disable_auto_select: true
```

--------------------------------

### Build Project

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Execute this command to generate the distributable files after making changes. This step is required before testing or pushing your contributions.

```bash
npm run build
```

--------------------------------

### Entity Configuration with Dynamic Music Assistant

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Use a Jinja template to dynamically select the Music Assistant entity based on Home Assistant states.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.office_homepod
    name: Office
    music_assistant_entity: |
      {% if is_state('input_boolean.target_office','on') %}
        media_player.office_homepod_2
      {% else %}
        media_player.kitchen_homepod_2
      {% endif %}
```

--------------------------------

### YAML Configuration for Source Selection Actions

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Configure custom actions to select media sources like Netflix, YouTube, or Hulu using their respective provider icons.

```yaml
actions:
  - icon: phu:netflix
    service: media_player.select_source
    service_data:
      entity_id: current
      source: Netflix
  - icon: phu:youtube
    service: media_player.select_source
    service_data:
      entity_id: current
      source: YouTube
  - icon: phu:hulu
    service: media_player.select_source
    service_data:
      entity_id: current
      source: Hulu
```

--------------------------------

### Entity Configuration with Static Music Assistant

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Associate a static Music Assistant companion entity with a media player for advanced features.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.kitchen_homepod
    name: Kitchen
    music_assistant_entity: media_player.kitchen_homepod_2
```

--------------------------------

### Basic Card Configuration with Multiple Entities

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Set up the YAMP card with multiple media player entities, assigning custom display names.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.living_room_apple_tv
    name: Living Room
  - entity_id: media_player.kitchen_homepod
    name: Kitchen
  - media_player.bedroom_speaker
```

--------------------------------

### Basic YAML Configuration for Yet Another Media Player

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

A fundamental configuration for the custom media player card, specifying the card type and entities to manage.

```yaml
type: custom:yet-another-media-player-beta
entities:
  - media_player.office_speaker_airplay
actions:
  - name: Set the Mood
    icon: mdi:heart
    service: script.set_mood
    script_variable: true
```

--------------------------------

### Define Custom Service Actions

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Create action chips to trigger any Home Assistant service. Use 'current' for entity_id to target the selected player, or specify a media ID for playback.

```yaml
type: custom:yet-another-media-player
entities:
  - media_player.living_room_apple_tv
actions:
  # Play a specific playlist
  - name: Grunge
    icon: mdi:music
    service: music_assistant.play_media
    service_data:
      entity_id: current
      media_id: apple_music://playlist/pl.8iqweuroqwjief209
      enqueue: replace

  # Call a custom script
  - name: Play Bluey
    icon: mdi:television-play
    service: script.play_bluey_on_living

  # Input source selection
  - icon: phu:netflix
    service: media_player.select_source
    service_data:
      entity_id: current
      source: Netflix
```

--------------------------------

### Volume Entity Configuration with Static Assignment and Power Sync

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Configure a static volume entity and enable power synchronization for volume control.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.living_room_apple_tv
    name: Living Room
    volume_entity: remote.living_room_apple_tv
    sync_power: true
```

--------------------------------

### Create Navigation Actions to Dashboard Views

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Create navigation actions to jump to specific dashboard views or pop-ups by setting `action: navigate` and providing a `navigation_path`.

```yaml
actions:
  - name: Living Room View
    icon: mdi:television
    action: navigate
    navigation_path: "#living"
```

--------------------------------

### Set Custom Actions with Icons

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Configure custom actions with Material Design Icons (mdi) to visually differentiate between music and TV related actions.

```yaml
actions:
  - icon: mdi:magnify
    menu_item: search
  - name: Grunge
    service: music_assistant.play_media
    icon: mdi:music
    service_data:
      entity_id: current
      media_id: apple_music://playlist/pl.8iqweuroqwjief209
      enqueue: replace
  - name: Play Bluey
    icon: mdi:television-play
    service: script.play_bluey_on_living
```

--------------------------------

### Minimal Card Configuration

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Configure the YAMP card with a single media player entity.

```yaml
type: custom:yet-another-media-player
entities:
  - media_player.living_room_speaker
```

--------------------------------

### Sync Selected Entity Actions

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Keep an `input_text` helper in sync with the currently selected media player. Use `sync_selected_entity` to sync to a helper and `select_entity` to select an entity from a helper.

```yaml
type: custom:yet-another-media-player
entities:
  - media_player.living_room_apple_tv
  - media_player.kitchen_homepod
actions:
  # Sync selected entity to helper
  - action: sync_selected_entity
    sync_entity_helper: input_text.yamp_selected_entity
    sync_entity_type: yamp_entity  # Options: yamp_entity, yamp_main_entity, yamp_playback_entity
    in_menu: hidden

  # Select entity from helper (inverse of sync)
  - action: select_entity
    sync_entity_helper: input_text.current_yamp_entity
    sync_entity_type: yamp_playback_entity
    in_menu: hidden
```

--------------------------------

### Enable Always Show Quick Grouping Mode

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Configure the card to always display Quick Grouping Mode by default using `always_show_quick_group: true`.

```yaml
type: custom:yet-another-media-player
  always_show_quick_group: true
entities:
  - entity_id: media_player.speaker_1
  - entity_id: media_player.speaker_2
```

--------------------------------

### Volume Entity Configuration Following Active Playback

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Configure the card to follow the active playback entity for volume control.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.kitchen_homepod
    name: Kitchen
    follow_active_volume: true
```

--------------------------------

### Volume Entity Configuration with Dynamic Assignment

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Use a Jinja template to dynamically select the volume entity, with power synchronization enabled.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.office_homepod
    name: Office
    volume_entity: |
      {% if is_state('input_boolean.tv_volume','on') %}
        remote.soundbar
      {% else %}
        media_player.office_homepod
      {% endif %}
    sync_power: true
```

--------------------------------

### Sync Selected Entity Action Configuration

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Configure the 'Sync Selected Entity' action to keep an `input_text` helper synchronized with the currently selected media player. This action runs in the background and is hidden by default.

```yaml
type: custom:yet-another-media-player
entities:
  - media_player.living_room_apple_tv
  - media_player.kitchen_homepod
actions:
  - action: sync_selected_entity
    sync_entity_helper: input_text.yamp_selected_entity
    in_menu: hidden
```

--------------------------------

### Enable Follow Active Volume

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Use `follow_active_volume: true` to make the volume entity automatically track the currently active playback entity. The sync power toggle is hidden when this is enabled.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.living_room_apple_tv
    name: Living Room
    follow_active_volume: true
  - entity_id: media_player.kitchen_homepod
    name: Kitchen
    follow_active_volume: true
```

--------------------------------

### Select Entity Action Configuration

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Configure the `select_entity` action to read an `input_text` helper and automatically activate the corresponding entity chip. This action runs passively in the background, monitoring helper state changes.

```yaml
actions:
  - action: select_entity
    sync_entity_helper: input_text.current_yamp_entity
    sync_entity_type: yamp_playback_entity
    in_menu: hidden
```

--------------------------------

### Configure Menu Item Actions

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Add action chips to open built-in card menus like search, source selection, or player grouping. Use 'in_menu: true' to place actions directly within the menu.

```yaml
type: custom:yet-another-media-player
entities:
  - media_player.living_room_apple_tv
actions:
  # Search action
  - icon: mdi:magnify
    menu_item: search

  # Group players menu (in menu placement)
  - name: Group Players
    icon: mdi:account-multiple-plus
    menu_item: group-players
    in_menu: true

  # Transfer queue
  - name: Transfer Queue
    transfer_queue: true
    in_menu: false
```

--------------------------------

### Behavior Configuration: Idle and Chip Display

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Configure idle behavior, including timeout and dimming, and control the visibility of chip rows.

```yaml
type: custom:yet-another-media-player
entities:
  - media_player.living_room_apple_tv
  - media_player.kitchen_homepod

# Idle and chip behavior
collapse_on_idle: true
idle_timeout_ms: 30000
dim_chips_on_idle: true
show_chip_row: in_menu  # Options: auto, always, in_menu, in_menu_on_idle
always_show_quick_group: true
```

--------------------------------

### Configure Navigation Actions

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Define navigation shortcuts to dashboard views, popups, or external URLs. Supports new tab opening and Jinja template paths for dynamic navigation.

```yaml
type: custom:yet-another-media-player
entities:
  - media_player.living_room_apple_tv
actions:
  # Navigate to a dashboard view
  - name: Living Room View
    icon: mdi:television
    action: navigate
    navigation_path: "#living"

  # Open external URL in new tab
  - name: Player Docs
    icon: mdi:open-in-new
    action: navigate
    navigation_path: "https://example.com/docs"
    navigation_new_tab: true

  # Dynamic navigation using Jinja templates
  - name: IMDb
    icon: mdi:movie-search
    action: navigate
    navigation_path: 'https://www.imdb.com/find/?q={{ state_attr(current, "media_title") }}'
    navigation_new_tab: true

  # Search for lyrics
  - name: Lyrics
    icon: mdi:music-clef-treble
    action: navigate
    navigation_path: 'https://genius.com/search?q={{ state_attr(current, "media_title") }} {{ state_attr(current, "media_artist") }}'
    navigation_new_tab: true
```

--------------------------------

### Launch External Sites in New Tab

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Configure navigation actions to open external websites in a new browser tab by setting `navigation_new_tab: true`.

```yaml
actions:
  - name: Player Docs
    icon: mdi:open-in-new
    action: navigate
    navigation_path: "https://example.com/docs"
    navigation_new_tab: true
```

--------------------------------

### Action Chip Configuration

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Define actions that can be displayed as chips or within menus.

```APIDOC
## Action Chip Configuration

### Description
Configure individual actions that can be displayed as chips or triggered via menus.

### Parameters
#### Request Body
- **transfer_queue** (menu action) - Optional - Adds a "Transfer Queue" menu action for Music Assistant entities.
- **name** (string) - Optional - Name for the action chip.
- **icon** (string) - Optional - MDI or custom icon for the action chip.
- **service** (string) - Optional - Home Assistant service to call (e.g., `media_player.play_media`).
- **service_data** (object) - Optional - Data to send with the service call.
- **action** (string) - Optional - Set to `navigate` for navigation shortcuts, `sync_selected_entity` to sync the active entity to a helper, `select_entity` to read a helper and activate the matching chip, or `prev_entity`/`next_entity` to navigate chips.
- **navigation_path** (string) - Optional - Destination for navigation shortcuts (supports anchors like `#pop-up-menu`, relative paths, or full URLs).
- **navigation_new_tab** (boolean) - Optional - When `true`, external URLs open in a new browser tab instead of replacing the current view (defaults to `false`).
- **menu_item** (string) - Optional - Opens a card menu by type: `search`, `search-recently-played`, `search-next-up`, `source`, `more-info`, `group-players`, `transfer-queue`.
- **in_menu** (choice) - Optional - Placement of the action: `false` (Action Chip), `true` (In Menu), or `hidden` (Hidden - only triggerable via card gestures) (defaults to `false`).
- **card_trigger** (choice) - Optional - Assign action to a card-level gesture: `none`, `tap`, `hold`, `double_tap`, `swipe_left`, or `swipe_right` (only for `hidden` actions) (defaults to `none`).
- **script_variable** (boolean) - Optional - Pass the currently selected entity as `yamp_entity` to a script (defaults to `false`).
- **sync_entity_helper** (string) - Optional - `input_text` entity to sync the currently selected entity to (used with `action: sync_selected_entity`).
```

--------------------------------

### Main YAMP Card for Two-Way Sync

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

This configuration for the main YAMP card includes both `sync_selected_entity` and `select_entity` actions to synchronize its state with an `input_text` helper and another YAMP card. It listens for changes from the search card.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.office_homepod_2
  - entity_id: media_player.kitchen_homepod_2
actions:
  - action: sync_selected_entity
    in_menu: hidden
    card_trigger: none
    sync_entity_type: yamp_playback_entity
    sync_entity_helper: input_text.current_yamp_entity
  - action: select_entity
    in_menu: hidden
    card_trigger: none
    sync_entity_type: yamp_playback_entity
    sync_entity_helper: input_text.current_yamp_entity
```

--------------------------------

### Artwork and Idle Settings

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Configure how artwork is displayed and when the player enters an idle state.

```APIDOC
## Artwork and Idle Settings

### Description
Configure visual aspects of the media player, including artwork display and idle behavior.

### Parameters
#### Request Body
- **artwork_hostname** (string) - Optional - Hostname URL (e.g., `http://192.168.1.50:8123`) prepended to relative artwork URLs; required when Casting to external devices
- **artwork_object_fit** (choice) - Optional - Control how artwork scales: `cover`, `contain`, `scaled-contain`, `scaled-contain-alternate`, `fill`, `scale-down`, `none`, or `no_artwork` (defaults to `cover`)
- **artwork_position** (choice) - Optional - Control artwork alignment: `top center`, `center center`, or `bottom center` (defaults to `top center`)
- **extend_artwork** (boolean) - Optional - When `true`, extends the artwork background up behind the chip and action rows for a full-bleed look (defaults to `false`)
- **media_artwork_overrides** (array) - Optional - Ordered artwork override rules. Provide an `image_url` and a single match key (title, artist, album, content id, channel, app name, content type, or entity) or supply `missing_art_url`; optional `size_percentage` and `object_fit` can be used to style the replacement (defaults to global `artwork_object_fit`). `image_url`/`missing_art_url` can be literal URLs or templates that resolve to one.
- **idle_image** (image/camera/url/template) - Optional - Background image when player is idle (supports local files, cameras, URLs, or templates that return either)
- **idle_timeout_ms** (number) - Optional - Timeout in milliseconds before showing idle image (0 = never go idle) (defaults to `60000`)
```

--------------------------------

### Customize Player Appearance

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Configure theme matching, appearance mode (light/dark), timestamp display, and progress bar style. Control the overall look and feel of the media player card.

```yaml
type: custom:yet-another-media-player
entities:
  - media_player.living_room_apple_tv

# Theme and appearance
match_theme: true
appearance: automatic  # Options: automatic, light, dark
display_timestamps: true
alternate_progress_bar: false

# Control layout
control_layout: modern  # Options: classic, modern
swap_pause_for_stop: true
adaptive_controls: true
volume_mode: slider  # Options: slider, stepper, hidden

# Typography
adaptive_text:
  - details
  - menu
  - action_chips
details_alignment: left  # Options: left, center, right, none
hide_active_entity_label: false

# Card sizing
card_height: 420

# Search view
search_view: card  # Options: list, card, card_minimal
search_card_columns: 4

# Collapsed states
collapse_on_idle: true
always_collapsed: false
expand_on_search: true
hide_menu_player: false
idle_screen: search-recently-played  # Options: default, search, search-recently-played, search-next-up
```

--------------------------------

### Configure Gesture Trigger Actions

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Assign actions to card-level gestures on the artwork area. Use `card_trigger` with options like `tap`, `hold`, `double_tap`, `swipe_left`, `swipe_right`. Set `in_menu: hidden` to hide from the action menu.

```yaml
type: custom:yet-another-media-player
entities:
  - media_player.living_room_apple_tv
actions:
  # Tap to open more info
  - icon: mdi:information
    menu_item: more-info
    in_menu: hidden
    card_trigger: tap

  # Hold to open search
  - icon: mdi:magnify
    menu_item: search
    in_menu: hidden
    card_trigger: hold

  # Double tap to toggle power
  - icon: mdi:power
    service: media_player.toggle
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: double_tap

  # Swipe left for next track
  - service: media_player.media_next_track
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: swipe_left

  # Swipe right for previous track
  - service: media_player.media_previous_track
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: swipe_right
```

--------------------------------

### Configure Artwork Display

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Control artwork scaling, positioning, and idle images. Set up custom artwork overrides based on media attributes like app name, content ID, or artist.

```yaml
type: custom:yet-another-media-player
entities:
  - media_player.living_room_apple_tv

# Artwork scaling and position
artwork_object_fit: scaled-contain  # Options: cover, contain, scaled-contain, scaled-contain-alternate, fill, scale-down, none, no_artwork
artwork_position: center center  # Options: top center, center center, bottom center
extend_artwork: true

# Artwork hostname for casting to external devices
artwork_hostname: "http://192.168.1.50:8123"

# Idle image (supports camera entities, image entities, URLs, or templates)
idle_image: camera.family_slideshow
idle_timeout_ms: 60000

# Artwork overrides for specific media
media_artwork_overrides:
  # Match by app name
  - image_url: https://upload.wikimedia.org/wikipedia/commons/6/62/YouTube_social_white_square_%282024%29.svg
    app_name: YouTube

  # Match by content ID
  - image_url: https://example.com/radio-logo.png
    media_content_id: library://radio/2

  # Match by artist
  - image_url: /local/images/KROQ.png
    media_artist: KROQ
    size_percentage: 85
    object_fit: contain

  # Fallback for missing artwork
  - missing_art_url: /local/images/default_station.png

  # Dynamic artwork using templates
  - image_url: "{{ states('sensor.bg_img_url') }}"
    entity_id: media_player.office_homepod_2
```

--------------------------------

### Artwork Overrides Configuration

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Define rules to replace missing or low-resolution artwork using `media_artwork_overrides`. Each override requires an `image_url` and a matching key (e.g., `app_name`, `media_artist`). Use `missing_art_url` to provide a fallback for all missing art.

```yaml
media_artwork_overrides:
  - image_url: >-
      https://upload.wikimedia.org/wikipedia/commons/6/62/YouTube_social_white_square_%282024%29.svg
    app_name: YouTube
  - image_url: https://shine1049.org/files/Stack%20Images/shine104.9.png?ade9fb8c3c
    media_content_id: library://radio/2
  - image_url: >-
      https://www.freepnglogos.com/uploads/youtube-tv-png/youtube-tv-youtube-watch-record-live-apk-download-from-moboplay-21.png
    app_name: YouTube TV
  - image_url: /local/images/KROQ.png
    media_artist: KROQ
  - missing_art_url: /local/images/default_station.png
  - image_url: "{{ states('sensor.bg_img_url') }}"
    entity_id: media_player.office_homepod_2
```

--------------------------------

### Enable Adaptive Controls in YAMP

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Set adaptive_controls to true to allow control buttons to stretch and gain padding as space becomes available. This results in larger, easier-to-press targets without affecting compact layouts.

```yaml
adaptive_controls: true
```

--------------------------------

### Configure Search Results Limit

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Set the maximum number of search results to display per media category. A value of 0 defers to Music Assistant's defaults. Higher limits may impact load times.

```yaml
type: custom:yet-another-media-player-alpha
search_results_limit: 50
entities:
  - entity_id: media_player.living_room_apple_tv
    name: Living Room
  - entity_id: media_player.kitchen_homepod
    name: Kitchen
```

--------------------------------

### Configure Adaptive Text Targets in YAMP

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Specify which sections of the YAMP card should have their text size adapt to available space. This allows for better readability in different dashboard layouts.

```yaml
adaptive_text_targets:
  - details
  - menu
  - action_chips
```

--------------------------------

### Configure Menu-Only Actions

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Set actions to appear only in the entity menu by setting `in_menu: true`. These actions preserve hover styling and icon color.

```yaml
actions:
  - name: Group Players
    icon: mdi:account-multiple-plus
    in_menu: true
    service: media_player.join
    service_data:
      entity_id: current
      group_members:
        - media_player.kitchen_homepod
```

--------------------------------

### Automation to Adjust Lights Based on Player State

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

This automation triggers when the selected entity in YAMP changes. It then adjusts lighting brightness based on which media player is currently selected, requiring an `input_text` helper to track the selected entity.

```yaml
alias: Adjust Lights Based on Selected Player
trigger:
  - platform: state
    entity_id: input_text.yamp_selected_entity
action:
  - choose:
      - conditions:
          - condition: state
            entity_id: input_text.yamp_selected_entity
            state: media_player.living_room_apple_tv
        sequence:
          - service: light.turn_on
            target:
              entity_id: light.living_room
            data:
              brightness_pct: 50
      - conditions:
          - condition: state
            entity_id: input_text.yamp_selected_entity
            state: media_player.kitchen_homepod
        sequence:
          - service: light.turn_on
            target:
              entity_id: light.kitchen
            data:
              brightness_pct: 75
```

--------------------------------

### Dedicated Search Card for Two-Way Sync

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

This search card configuration also includes `select_entity` and `sync_selected_entity` actions to maintain synchronization with an `input_text` helper and another YAMP card. It listens for changes from the main card.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.office_homepod_2
  - entity_id: media_player.kitchen_homepod_2
control_layout: modern
card_type: search
search_view: card_minimal
idle_screen: search
actions:
  - action: select_entity
    in_menu: hidden
    card_trigger: none
    sync_entity_type: yamp_playback_entity
    sync_entity_helper: input_text.current_yamp_entity
  - action: sync_selected_entity
    in_menu: hidden
    card_trigger: none
    sync_entity_type: yamp_playback_entity
    sync_entity_helper: input_text.current_yamp_entity
```

--------------------------------

### Use Modern Control Layout in YAMP

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Set control_layout to 'modern' to use Home Assistant-style buttons for playback controls. This layout places shuffle, previous, play/pause, next, and repeat inline, with favorite and power buttons in the volume row.

```yaml
control_layout: modern
```

--------------------------------

### Configure Search Behavior

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Set search limits, sorting, default filters, and autofocus behavior. These options control how search results are displayed and managed.

```yaml
search_results_limit: 50
search_results_sort: timestamp_added_desc  # Options: default, name, name_desc, timestamp_added, last_played, play_count, random, etc.
default_search_filter: track  # Options: all, artist, album, track, playlist, radio, podcast, audiobook
default_search_favorites: true
keep_filters_on_search: false
disable_autofocus: false
pin_search_headers: true
dismiss_search_on_play: true
```

--------------------------------

### Gesture Triggers: Double Tap and Swipe Actions

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Configure gesture triggers for double tap, swipe left, and swipe right. These actions are hidden from the menu and trigger media player controls.

```yaml
actions:
  - icon: mdi:power
    service: media_player.toggle
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: double_tap
  - service: media_player.media_next_track
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: swipe_left
  - service: media_player.media_previous_track
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: swipe_right
```

--------------------------------

### Set Idle Screen to Search

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Configure the `idle_screen` option to automatically jump to a specific search view when the player is idle. Supported values include `search`, `search-recently-played`, and `search-next-up`.

```yaml
idle_screen: search-recently-played
```

--------------------------------

### Configure Search Results Sorting

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Customize the order of search results by specifying a sort key and direction. Sorting is handled server-side by Music Assistant.

```yaml
type: custom:yet-another-media-player-alpha
search_results_sort: timestamp_added_desc
entities:
  - entity_id: media_player.office_homepod
    name: Office
```

--------------------------------

### Register New Language

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

To add a new translation, import the language file and add it to the 'languages' object in 'src/localize/localize.js'.

```javascript
import fr from './languages/fr.js';

const languages = {
  en,
  fr,
};
```

--------------------------------

### Gesture-Only Minimal Card Configuration

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Create a minimalist YAMP card that relies solely on gestures for control by hiding all standard playback buttons. This configuration is suitable for touch-based interfaces like tablets or wall panels.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.office_homepod
    name: Office
    hidden_controls:
      - previous
      - play_pause
      - stop
      - next
      - shuffle
      - repeat
      - favorite
      - power
show_chip_row: in_menu
alternate_progress_bar: true
volume_mode: hidden
actions:
  - service: media_player.media_play_pause
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: tap
    name: Play/Pause
  - service: media_player.volume_down
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: hold
    name: Volume Down
  - service: media_player.volume_up
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: double_tap
    name: Volume Up
  - service: media_player.media_next_track
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: swipe_left
    name: Next Track
  - service: media_player.media_previous_track
    service_data:
      entity_id: current
    in_menu: hidden
    card_trigger: swipe_right
    name: Previous Track
```

--------------------------------

### Play Radio Station with Chromecast Metadata

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Configure YAMP to play a radio station on Chromecast devices, including custom metadata and artwork. Ensure the `media_player.chromecast_living_room` entity is correctly set up.

```yaml
type: custom:yet-another-media-player
entities:
  - media_player.chromecast_living_room
actions:
  - name: Jazz Radio
    icon: mdi:radio
    service: media_player.play_media
    service_data:
      entity_id: current
      media_content_id: https://streaming.live365.com/a49833
      media_content_type: music
      extra:
        metadata:
          metadataType: 3
          title: KJazz 88.1
          subtitle: KJazz 88.1
          images:
            - url: https://cdn-profiles.tunein.com/s37062/images/logod.jpg
```

--------------------------------

### Enable Adaptive Text Scaling in YAMP

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Set adaptive_text to true to enable scaling of text elements like titles, menu entries, and chips based on available space. This improves readability in both compact and spacious layouts.

```yaml
adaptive_text: true
```

--------------------------------

### Dedicated Search Card Mode

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Configure a specialized card interface for search functionality by setting `card_type: search`. This mode allows for specific search-related configurations like `search_view` and `idle_screen`.

```yaml
# Dedicated search card
type: custom:yet-another-media-player
card_type: search
entities:
  - entity_id: media_player.office_homepod_2
  - entity_id: media_player.kitchen_homepod_2
control_layout: modern
search_view: card_minimal
idle_screen: search
hide_menu_player: false
```

--------------------------------

### Hidden Controls Configuration

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Hide specific media player controls like favorite, shuffle, repeat, or power on a per-entity basis.

```yaml
type: custom:yet-another-media-player
entities:
  - entity_id: media_player.living_room_apple_tv
    name: Living Room
    hidden_controls:
      - favorite
      - shuffle
      - repeat
  - entity_id: media_player.kitchen_homepod
    name: Kitchen
    hidden_controls:
      - power
```

--------------------------------

### Increase Font Size for Details Row

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Use card-mod to increase the font size for the details row, title, and artist. Adjust the `em` values to your preference.

```yaml
card_mod:
  style: |
    .details {
      font-size: 2.4em !important;      # overall scaling
    }
    .details .title {
      font-size: 1.6em !important;      # optional: title only
    }
    .details .artist {
      font-size: 1.2em !important;      # optional: artist only
    }
```

--------------------------------

### Script Variable Passing

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Pass the currently selected entity to a script using `script_variable: true`. The script will receive `yamp_entity`, `yamp_main_entity`, and `yamp_playback_entity` variables.

```yaml
# Card configuration
type: custom:yet-another-media-player
entities:
  - media_player.office_speaker_airplay
actions:
  - name: Set the Mood
    icon: mdi:heart
    service: script.set_mood
    script_variable: true

# Example script in scripts.yaml
set_mood:
  alias: Set the Mood
  mode: single
  fields:
    yamp_entity:
      description: Target media player (MA entity if configured, else main entity)
    yamp_main_entity:
      description: Main configured entity
    yamp_playback_entity:
      description: Currently active playback entity
  sequence:
    - action: light.turn_off
      target:
        entity_id: light.bedroom
    - action: switch.turn_on
      target:
        entity_id: switch.fireplace
    - service: music_assistant.play_media
      data:
        entity_id: "{{ yamp_entity }}"
        media_id: apple_music://track/1445094678
        enqueue: replace
```

--------------------------------

### Dedicated Group Players Card Mode

Source: https://context7.com/jianyu-li/yet-another-media-player/llms.txt

Create a specialized card interface for managing group players by setting `card_type: group_players`. This mode is useful for displaying and controlling multiple media players that can be grouped.

```yaml
# Dedicated group players card
type: custom:yet-another-media-player
card_type: group_players
entities:
  - media_player.living_room_speaker
  - media_player.kitchen_speaker
  - media_player.bedroom_speaker
```

--------------------------------

### Enable Dedicated Search Mode in YAMP

Source: https://github.com/jianyu-li/yet-another-media-player/blob/main/README.md

Set the card_type to 'search' to transform YAMP into a permanent search interface. This is useful for creating dedicated search pages or sidebar search components.

```yaml
card_type: search
```