Get library items

Use this action to retrieve items from your Music Assistant library. It gives you programmatic access to concise information about your library items, which you can use to build a queue of tracks for playback.

This action returns its result in a response variable, which you can use in later steps of the same automation or script. It does not change anything on a player.

Using this action from the user interface

If you prefer building automations and scripts visually, Home Assistant walks you through this action step by step. You pick what to target, tweak a few options, and save. No YAML knowledge required.

To get library items from an automation or a script:

1. Go to Settings > Automations & scenes.
2. Open an existing automation or script, or select Create automation > Create new automation.
3. If you’re setting up a new automation, add a trigger in the When section. Scripts don’t need a trigger. They run when something else calls them.
4. In the Then do section, select Add action.
5. From the search box, search for and select Music Assistant: Get library items.
6. Fill in the options you want to use.
7. In the Response variable field, enter a name to store the data in, such as library_items.
8. Select Save.

This action does not support targets. In the UI, you are not prompted to choose an area, device, entity, or label. You select the Music Assistant instance through the Music Assistant instance option instead.

Options in the UI

Using this action in YAML

If you work directly in YAML, or you want to know exactly what Home Assistant does under the hood, this section has the technical reference. It lists the field names you use in YAML, their types, and which ones are required.

In YAML, refer to this action as music_assistant.get_library. A basic example looks like this:

action: music_assistant.get_library
data:
  config_entry_id: 01JEXNDHT21V0BHJXM7A5SZANV
  media_type: track
response_variable: library_items

Options in YAML

Response data

The action returns an items list with the matching library items, along with the limit, offset, order_by, and media_type you requested. Each item includes details such as its name and URI, which you can pass to the Play media action.

This example starts playback of ten random tracks:

sequence:
  - action: music_assistant.get_library
    data:
      config_entry_id: 01JEXNDHT21V0BHJXM7A5SZANV
      media_type: track
      limit: 10
      order_by: random
    response_variable: random_tracks
  - action: music_assistant.play_media
    target:
      entity_id: media_player.kitchen_speaker
    data:
      media_id: "{{ random_tracks['items'] | map(attribute='uri') | list }}"
      media_type: track
      enqueue: replace

Still stuck?

The Home Assistant community is quick to help: join Discord for real-time chat, post on the community forum with the action you’re calling and what you expected to happen, or share on our subreddit /r/homeassistant.

Related actions

These actions work well alongside this one:

• Search Music Assistant: Performs a global search on the Music Assistant library and all providers.

• Play media: Plays media on a Music Assistant player with fine-grained control options.