Skip to content

Add missing services, commands to readme; add service schemas #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
droans merged 5 commits into from
Apr 17, 2026
Merged

Add missing services, commands to readme; add service schemas #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3ac58f1
Add missing services to readme
droans Apr 17, 2026
734419e
Use collapsed groups to simplify readme
droans Apr 17, 2026
cf52522
Small formatting fixes
droans Apr 17, 2026
ce03deb
Add WebSocket commands
droans Apr 17, 2026
f7a5fc4
Add response schemas
droans Apr 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 155 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,17 @@ 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)

---

<details>
<summary>Queue Actions</summary>

`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. |
Expand Down Expand Up @@ -103,7 +109,153 @@ 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.

| 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 |

</summary>

<details>
<summary>Group Actions</summary>

`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 |

</summary>

<details>
<summary>Collection Actions</summary>

`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) |

---
### Albums
`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. |

---
### Artists
`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. |

---
### Playlists
`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.

---

### Podcasts
`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. |

</summary>

## 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

Expand Down
164 changes: 164 additions & 0 deletions docs/response_schemas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<Base64 encoded string representation of image>
```

## 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)*
Loading