From 9d85d1ac18dbd115e20c82cbb5841f521464e6d4 Mon Sep 17 00:00:00 2001
From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
Date: Wed, 8 Jan 2025 18:08:12 +0100
Subject: [PATCH] Add actions to Music Assistant (#36469) (#36784)

Co-authored-by: OzGav <gavnosp@hotmail.com>
---
 source/_integrations/music_assistant.markdown | 83 +++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/source/_integrations/music_assistant.markdown b/source/_integrations/music_assistant.markdown
index 1e17e065662..08e8b267f01 100644
--- a/source/_integrations/music_assistant.markdown
+++ b/source/_integrations/music_assistant.markdown
@@ -135,6 +135,89 @@ Transfer the player's queue to another player.
   - **Description**: Start playing the queue on the target player. Omit to use the default behavior.
   - **Example**: `true`
 
+### Action `music_assistant.search`
+
+Perform a global search on the Music Assistant library and all providers.
+
+- **Data attribute**: `config_entry_id`
+  - **Optional**: No.
+  - **Description**: The Music Assistant instance that the search will be performed upon. Allows for multiple servers to be running.
+  - **Example**: `Music Assistant`
+- **Data attribute**: `name`
+  - **Optional**: No.
+  - **Description**: The name/title to search for.
+  - **Example**: `We Are The Champions`
+- **Data attribute**: `media_type`
+  - **Optional**: Yes.
+  - **Description**: The type(s) of content to search for. Select from artist, album, track, radio, or playlist. All types if omitted.
+  - **Example**: `playlist`
+- **Data attribute**: `artist`
+  - **Optional**: Yes.
+  - **Description**: When specifying a track or album in the name field, you can optionally restrict results by this artist name.
+  - **Example**: `Queen`
+- **Data attribute**: `album`
+  - **Optional**: Yes.
+  - **Description**: When specifying a track in the name field, you can optionally restrict results by this album name.
+  - **Example**: `News of the world`
+- **Data attribute**: `limit`
+  - **Optional**: Yes.
+  - **Description**: Maximum number of items to return (per media type).
+  - **Example**: `10`
+- **Data attribute**: `library_only`
+  - **Optional**: Yes.
+  - **Description**: Only include results that are in the library.
+  - **Example**: `true`
+  
+### Action `music_assistant.get_library`
+
+Perform a local search on the Music Assistant library.
+
+- **Data attribute**: `config_entry_id`
+  - **Optional**: No.
+  - **Description**: The Music Assistant instance that the search will be performed upon. Allows for multiple servers to be running.
+  - **Example**: `Music Assistant`
+- **Data attribute**: `media_type`
+  - **Optional**: No.
+  - **Description**: The type of content to search for. Select from artist, album, track, radio, or playlist.
+  - **Example**: `artist`
+- **Data attribute**: `favorite`
+  - **Optional**: Yes.
+  - **Description**: When selected, only items marked as favorites will be returned.
+  - **Example**: `false`
+- **Data attribute**: `limit`
+  - **Optional**: Yes.
+  - **Description**: Maximum number of items to return.
+  - **Example**: `25`
+- **Data attribute**: `offset`
+  - **Optional**: Yes.
+  - **Description**: From what point in the list should results be returned.
+  - **Example**: `10`
+- **Data attribute**: `search`
+  - **Optional**: Yes.
+  - **Description**: A string that will further filter the results.
+  - **Example**: `Home`
+- **Data attribute**: `order_by`
+  - **Optional**: Yes.
+  - **Description**: Sort the list by this field. View available sorting options in the Developer Tools > Actions > music_assistant.get_library action.
+  - **Example**: `year`
+- **Data attribute**: `album_artists_only`
+  - **Optional**: Yes.
+  - **Description**: When `artist` is the `media_type` then this option will restrict the result to album artists only.
+  - **Example**: `true`
+- **Data attribute**: `album_type`
+  - **Optional**: Yes.
+  - **Description**: When `album` is the `media_type` then this option will restrict the result according to the selection of either album, single, compilation, EP or unknown.
+  - **Example**: `album`
+
+### Action `music_assistant.get_queue`
+
+Get the queue details of a Music Assistant player queue.
+
+- **Data attribute**: `entity_id`
+  - **Optional**: No.
+  - **Description**: The entity_id of the player holding the queue to be retrieved.
+  - **Example**: `media_player.kitchen_speaker`
+
 ## Notes
 
 - Any Home Assistant players added to Music Assistant will appear duplicated as the MA version of the player is created. The original HA player can be hidden if desired.