From 3ac58f15753ad15e15eb68759872d754449c6052 Mon Sep 17 00:00:00 2001 From: Michael Carroll Date: Fri, 17 Apr 2026 11:51:38 -0400 Subject: [PATCH 1/5] Add missing services to readme --- README.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) diff --git a/README.md b/README.md index e4fd0e4..d4a8e13 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,113 @@ media_player.music_assistant_speaker: | `data` | dict | No | None | Any data to send with the command | | `config_entry_id` | dict | No | None | The ID of the used `mass_queue` integration | +`mass_queue.clear_queue_from_here`: Clear the items in a queue after the currently playing item. + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------------------------| +| `entity` | str | Yes | n/a | Music assistant player entity | + +`mass_queue.unfavorite_current_item`: Unfavorite the currently playing item + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------------------------| +| `entity` | str | Yes | n/a | Music assistant player entity | + +`mass_queue.set_group_volume`: Sets the volume for the group which the provided player belongs to. + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------------------------| +| `entity` | str | Yes | n/a | Music assistant player entity | + +`mass_queue.get_group_volume`: Returns the volume for a player group. + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------------------------| +| `entity` | str | Yes | n/a | Music assistant player entity | + +`mass_queue.get_recommendations`: Get recommendations from your music providers. + +| Parameter | Type | Required | Default | Description | +|--------------|-------------|----------|---------|----------------------------------------------------| +| `entity` | str | Yes | n/a | Music assistant player entity | +| `providers` | list of str | No | n/a | Limit recommendations to the specified provider(s) | + +`mass_queue.get_album`: Returns information about an album from the MA server. + +| Parameter | Type | Required | Default | Description | +|-------------------|------|----------|---------|---------------------------------------------| +| `config_entry_id` | str | No | None | The ID of the used `mass_queue` integration | +| `uri` | str | Yes | n/a | The URI for the playlist | + +`mass_queue.get_album_tracks`: Returns some or all tracks for the album given by the URI. + +| Parameter | Type | Required | Default | Description | +|-------------------|------|----------|---------|----------------------------------------------------------| +| `config_entry_id` | str | No | None | The ID of the used `mass_queue` integration | +| `uri` | str | Yes | n/a | The URI for the album | +| `page` | int | No | None | Page of results to return. If not provided, returns all. | +`mass_queue.get_artist`: Returns information about an artist from the MA server. + +| Parameter | Type | Required | Default | Description | +|-------------------|------|----------|---------|---------------------------------------------| +| `config_entry_id` | str | No | None | The ID of the used `mass_queue` integration | +| `uri` | str | Yes | n/a | The URI for the playlist | + +`mass_queue.get_artist_tracks`: Returns the top tracks for the artist given by the URI. + +| Parameter | Type | Required | Default | Description | +|-------------------|------|----------|---------|----------------------------------------------------------| +| `config_entry_id` | str | No | None | The ID of the used `mass_queue` integration | +| `uri` | str | Yes | n/a | The URI for the artist | +| `page` | int | No | None | Page of results to return. If not provided, returns all. | + +`mass_queue.get_playlist`: Returns information about a playlist from the MA server. + +| Parameter | Type | Required | Default | Description | +|-------------------|------|----------|---------|---------------------------------------------| +| `config_entry_id` | str | No | None | The ID of the used `mass_queue` integration | +| `uri` | str | Yes | n/a | The URI for the playlist | + +`mass_queue.get_playlist_tracks`: Returns some or all tracks for the playlist given by the URI. + +| Parameter | Type | Required | Default | Description | +|-------------------|------|----------|---------|----------------------------------------------------------| +| `config_entry_id` | str | No | None | The ID of the used `mass_queue` integration | +| `uri` | str | Yes | n/a | The URI for the playlist | +| `page` | int | No | None | Page of results to return. If not provided, returns all. | + +`mass_queue.remove_playlist_tracks`: Removes one or more tracks from a playlist based on their position. **IMPORTANT: SEE WARNING BELOW** + +| Parameter | Type | Required | Default | Description | +|-----------------------|-------------|----------|---------|---------------------------------------------------| +| `config_entry_id` | str | Yes | n/a | The ID of the used `mass_queue` integration | +| `playlist_id` | str | Yes | n/a | The ID of the playlist | +| `positions_to_remove` | list of str | Yes | n/a | Position(s) of items to remove from the playlist. | + +### ⚠️WARNING: mass_queue.remove_playlist_tracks is bad for your health.⚠️ + +`mass_queue.remove_playlist_tracks` is **dangerous**. + +Music Assistant will use the positions in a playlist to determine which tracks to remove. However, it does not provide an updated playlist immediately, instead waiting for the next refresh. + +You must be **VERY** careful if you are using this action. You should **NOT** rely on proper feedback from Music Assistant. If you plan on using this, you MUST plan to work around this. + +`mass_queue.get_podcast`: Returns information about a podcast from the MA server. + +| Parameter | Type | Required | Default | Description | +|-------------------|------|----------|---------|---------------------------------------------| +| `config_entry_id` | str | No | None | The ID of the used `mass_queue` integration | +| `uri` | str | Yes | n/a | The URI for the playlist | + +`mass_queue.get_podcast_episodes`: Returns some or all episodes for the podcast given by the URI. + +| Parameter | Type | Required | Default | Description | +|-------------------|------|----------|---------|----------------------------------------------------------| +| `config_entry_id` | str | No | None | The ID of the used `mass_queue` integration | +| `uri` | str | Yes | n/a | The URI for the podcast | +| `page` | int | No | None | Page of results to return. If not provided, returns all. | + + ## Installation 1. Download and install the integration by using the button above. From 734419e723b8c21a66ae6611231fd18f10a15813 Mon Sep 17 00:00:00 2001 From: Michael Carroll Date: Fri, 17 Apr 2026 11:52:18 -0400 Subject: [PATCH 2/5] Use collapsed groups to simplify readme --- README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.md b/README.md index d4a8e13..3767804 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,10 @@ Designed to work with [Music Assistant Player Card](https://github.com/droans/ma ## New actions: --- + +
+Queue Actions + `mass_queue.get_queue_items`: Returns the items (songs, podcast episods, etc.) within a queue | Parameter | Type | Required | Default | Description | @@ -117,6 +121,11 @@ media_player.music_assistant_speaker: |-----------|------|----------|---------|-------------------------------| | `entity` | str | Yes | n/a | Music assistant player entity | + + +
+Group Actions + `mass_queue.set_group_volume`: Sets the volume for the group which the provided player belongs to. | Parameter | Type | Required | Default | Description | @@ -129,6 +138,11 @@ media_player.music_assistant_speaker: |-----------|------|----------|---------|-------------------------------| | `entity` | str | Yes | n/a | Music assistant player entity | + + +
+Collection Actions + `mass_queue.get_recommendations`: Get recommendations from your music providers. | Parameter | Type | Required | Default | Description | @@ -136,6 +150,8 @@ media_player.music_assistant_speaker: | `entity` | str | Yes | n/a | Music assistant player entity | | `providers` | list of str | No | n/a | Limit recommendations to the specified provider(s) | +--- +### Albums `mass_queue.get_album`: Returns information about an album from the MA server. | Parameter | Type | Required | Default | Description | @@ -150,6 +166,9 @@ media_player.music_assistant_speaker: | `config_entry_id` | str | No | None | The ID of the used `mass_queue` integration | | `uri` | str | Yes | n/a | The URI for the album | | `page` | int | No | None | Page of results to return. If not provided, returns all. | + +--- +### Artists `mass_queue.get_artist`: Returns information about an artist from the MA server. | Parameter | Type | Required | Default | Description | @@ -165,6 +184,8 @@ media_player.music_assistant_speaker: | `uri` | str | Yes | n/a | The URI for the artist | | `page` | int | No | None | Page of results to return. If not provided, returns all. | +--- +### Playlists `mass_queue.get_playlist`: Returns information about a playlist from the MA server. | Parameter | Type | Required | Default | Description | @@ -196,6 +217,9 @@ Music Assistant will use the positions in a playlist to determine which tracks t You must be **VERY** careful if you are using this action. You should **NOT** rely on proper feedback from Music Assistant. If you plan on using this, you MUST plan to work around this. +--- + +### Podcasts `mass_queue.get_podcast`: Returns information about a podcast from the MA server. | Parameter | Type | Required | Default | Description | @@ -211,6 +235,7 @@ You must be **VERY** careful if you are using this action. You should **NOT** re | `uri` | str | Yes | n/a | The URI for the podcast | | `page` | int | No | None | Page of results to return. If not provided, returns all. | + ## Installation From cf5252208c1ae9d640daf64dcced786eb4e449b5 Mon Sep 17 00:00:00 2001 From: Michael Carroll Date: Fri, 17 Apr 2026 11:55:42 -0400 Subject: [PATCH 3/5] Small formatting fixes --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3767804..f0db8d4 100644 --- a/README.md +++ b/README.md @@ -40,8 +40,8 @@ Designed to work with [Music Assistant Player Card](https://github.com/droans/ma `mass_queue.get_queue_items`: Returns the items (songs, podcast episods, etc.) within a queue -| Parameter | Type | Required | Default | Description | -|-----------|------|----------|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Parameter | Type | Required | Default | Description | +|-----------------|------|----------|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `entity` | str | Yes | n/a | Music assistant player entity | | `limit` | int | No | 500 | Number of items in queue to return | | `offset` | int | No | n/a | Location in queue to start where zero equals the first item in queue, not the current item. By default, will start with five items before actively playing item. | @@ -107,7 +107,7 @@ media_player.music_assistant_speaker: |-------------------|------|----------|---------|---------------------------------------------| | `command` | str | Yes | n/a | The command to send to Music Assistant | | `data` | dict | No | None | Any data to send with the command | -| `config_entry_id` | dict | No | None | The ID of the used `mass_queue` integration | +| `config_entry_id` | str | No | None | The ID of the used `mass_queue` integration | `mass_queue.clear_queue_from_here`: Clear the items in a queue after the currently playing item. From ce03deb644a6184d4a06f970f37df74c5451c837 Mon Sep 17 00:00:00 2001 From: Michael Carroll Date: Fri, 17 Apr 2026 13:18:17 -0400 Subject: [PATCH 4/5] Add WebSocket commands --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/README.md b/README.md index f0db8d4..b33137f 100644 --- a/README.md +++ b/README.md @@ -237,6 +237,24 @@ You must be **VERY** careful if you are using this action. You should **NOT** re +## New Websocket Commands: + +The WebSocket commands below can be used by custom cards/integrations along with whatever personal use you may discern. + +`mass_queue/get_info`: Returns basic information about a Music Assistant player. + +| Parameter | Type | Required | Description | +|-------------------|------|----------|---------|----------------------| +| `type` | str | Yes | Must be `mass_queue/get_info` | +| `entity_id` | str | Yes | Music assistant player entity | + +`mass_queue/download_and_encode_image`: Returns a single image for a media item as a Base64 encoded string. Useful when avoiding mixed-content or when accessing local media outside of your network + +| Parameter | Type | Required | Description | +|-------------------|------|----------|---------|---------------------------------------| +| `type` | str | Yes | Must be `mass_queue/download_and_encode_image` | +| `url` | str | Yes | URL of media to download. | + ## Installation 1. Download and install the integration by using the button above. From f7a5fc4af898f3fd29acc8b6436687e9dd674e8d Mon Sep 17 00:00:00 2001 From: Michael Carroll Date: Fri, 17 Apr 2026 13:19:36 -0400 Subject: [PATCH 5/5] Add response schemas --- README.md | 2 + docs/response_schemas.md | 164 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 166 insertions(+) create mode 100644 docs/response_schemas.md diff --git a/README.md b/README.md index b33137f..341c8c9 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,8 @@ Designed to work with [Music Assistant Player Card](https://github.com/droans/ma ## New actions: +The response schemas for all new actions and WebSocket commands can be found at [docs/response_schemas.md](docs/response_schemas.md) + ---
diff --git a/docs/response_schemas.md b/docs/response_schemas.md new file mode 100644 index 0000000..d7cd99f --- /dev/null +++ b/docs/response_schemas.md @@ -0,0 +1,164 @@ +# Schemas + +## Service Schemas + +### GetQueueItemsResponseSchema + +```yaml +[player_name: str]: QueueItemSchema[] +``` + +### GetGroupVolumeResponseSchema + +```yaml +volume_level: int +``` + + +### SendCommandResponseSchema + +```yaml +response: any +``` + +### GetRecommendationsResponseSchema + +```yaml +response: RecommendationFolder[] +``` + +### GetAlbumResponseSchema + +*See [music_assistant_models.media_items.Album](https://github.com/music-assistant/models/blob/0f2ad708ab26d2cc2ae008872afc00cd4a795380/music_assistant_models/media_items/media_item.py#L208)* + + +### GetArtistResponseSchema + +*See [music_assistant_models.media_items.Artist](https://github.com/music-assistant/models/blob/0f2ad708ab26d2cc2ae008872afc00cd4a795380/music_assistant_models/media_items/media_item.py#L198)* + +### GetPlaylistResponseSchema + +*See [music_assistant_models.media_items.Playlist](https://github.com/music-assistant/models/blob/0f2ad708ab26d2cc2ae008872afc00cd4a795380/music_assistant_models/media_items/media_item.py#L254)* + +### GetPodcastResponseSchema + +*See [music_assistant_models.media_items.Podcast](https://github.com/music-assistant/models/blob/0f2ad708ab26d2cc2ae008872afc00cd4a795380/music_assistant_models/media_items/media_item.py#L323)* + +### GetAlbumTracksResponseSchema + +```yaml +tracks: TrackSchame[] +``` + +### GetArtistTracksResponseSchema + +```yaml +tracks: TrackSchame[] +``` + +### GetPlaylistTracksResponseSchema + +```yaml +tracks: PlaylistTrackSchema[] +``` + +### GetPodcastEpisodesResponseSchema + +```yaml +episodes: PodcastEpisodeSchema[] +``` + +## WebSocket Schemas + +### GetInfoResponseSchema + +```yaml +available: bool +can_group_with: str[] # List of player IDs that can be natively synced using `media_player.join` +connection: + configuration_url: str # URL to configure the player from Music Assistant + url: str # IP Address for player +entries: # Config Entry IDs for the player's HA integrations + music_assistant: str + mass_queue: str +features: str[] # List of features which the player supports +manufacturer: str +model: str +name: str +player_id: str # ID of player in Music Assistant +provider: str +queue_id: str # ID for queue currently playing on player +server: + connection: + url: str # URL to access Music Assistant integration + websocket: str # WebSocket address to interact with player +synced_to: str| None # Player(s) which are currently synced/grouped/joined with the player +type: str +``` + +### DownloadAndEncodeImageResponseSchema + +```yaml + +``` + +## Sub-schemas + +### QueueItemSchema + +```yaml +queue_item_id: str +media_title: str +media_album_name: str +media_artist: str +media_content_id: str +media_image: str +favorite: bool +``` + +### TrackSchema + +```yaml +media_title: str +media_content_id: str +duration?: int +media_image: str +local_image_encoded?: str +favorite: bool +media_album_name: str +media_artist: str +``` + +### PlaylistTrackSchema + +```yaml +media_title: str +media_content_id: str +duration?: int +media_image: str +local_image_encoded?: str +favorite: bool +media_album_name: str +media_artist: str +position: int +``` + +### PodcastEpisodeSchema + +```yaml +media_title: str +media_content_id: str +duration?: int +media_image: str +local_image_encoded?: str +favorite: bool +media_album_name: str +media_artist: str +release_date: str +``` + +*Note: release date is a string representation of a date, formatted as `YYYY-MM-DDTHH:MM:SS`.* + +### RecommendationFolder + +*See [music_assistant_models.media_items.RecommendationFolder](https://github.com/music-assistant/models/blob/0f2ad708ab26d2cc2ae008872afc00cd4a795380/music_assistant_models/media_items/media_item.py#L389)*