diff --git a/README.md b/README.md index e4fd0e4..341c8c9 100644 --- a/README.md +++ b/README.md @@ -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) + --- + +
+Queue Actions + `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. | @@ -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 | + + + +
+Group Actions + +`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 | + + + +
+Collection Actions + +`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. | + + + +## 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 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)*