Music Assistant Client

1.3.5 · active · verified Fri Apr 17

`music-assistant-client` is the official asynchronous Python client library for Music Assistant, a powerful server that unifies various music sources (streaming services, local files) into a single library. It allows programmatic interaction with your Music Assistant instance to manage playback, browse libraries, and more. The current version is 1.3.5, with frequent updates focused on stability and new features.

Common errors

```
ModuleNotFoundError: No module named 'music_assistant_client'
```
cause The `music-assistant-client` package is not installed in your current Python environment.

fix Run `pip install music-assistant-client` to install the library.
```
TypeError: object MusicAssistantClient can't be used in 'await' expression
```
cause You are trying to `await` the `MusicAssistantClient` *class* or an already connected instance, instead of its asynchronous methods (like `connect()`). This usually means you forgot `await` on a method call.

fix Ensure you are awaiting specific asynchronous methods, e.g., `await mass_client.connect()` or `await mass_client.music.get_all_artists()`.
```
aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host localhost:8095 ssl:False [Connection refused]
```
cause The Music Assistant server is not running, is inaccessible, or the specified host/port is incorrect. This is a network connection issue.

fix Check if your Music Assistant server is running and reachable at the provided URL (e.g., `http://localhost:8095`). Verify the IP address and port, and check any firewall rules.
```
AttributeError: 'MusicAssistantClient' object has no attribute 'music'
```
cause You are attempting to access client features (like `mass_client.music`) before successfully establishing a connection to the Music Assistant server with `await mass_client.connect()`.

fix Always call and `await` `mass_client.connect()` before attempting to use any other client methods.

Warnings

breaking Version 1.0.0 introduced a complete rewrite to a fully asynchronous client, requiring all API calls to be awaited. Code written for pre-1.0.0 synchronous versions will no longer work.
Fix: Rewrite client interaction to use `await` for all method calls and ensure the code runs within an `async` context (e.g., using `asyncio.run()`).
gotcha Forgetting to `await` asynchronous method calls (e.g., `mass_client.connect()`) will lead to `TypeError` or `RuntimeWarning` exceptions, as the coroutine object is not executed.
Fix: Always prepend `await` to any call that returns a coroutine (e.g., `await mass_client.connect()`, `await mass_client.music.get_music_providers()`).
gotcha The client library requires an active Music Assistant server running and accessible at the specified URL. A `ConnectionRefusedError` (or similar) will occur if the server is offline or the URL/port is incorrect.
Fix: Verify your Music Assistant server is running, check the specified URL and port, and ensure no firewalls are blocking the connection. The default port is 8095.

Install

pip install music-assistant-client Install stable release

Imports

MusicAssistantClient
wrong:
```
from musicassistantclient import MusicAssistantClient
```
correct:
```
from music_assistant_client import MusicAssistantClient
```
Python package names often convert hyphens to underscores for import paths. Do not use the hyphenated package name directly for imports.
MusicAssistantError
```
from music_assistant_client.exceptions import MusicAssistantError
```
Specific exceptions are found within the `exceptions` submodule.

Quickstart

This quickstart demonstrates how to connect to a Music Assistant server, retrieve server information, and list available music providers. Remember to replace `http://localhost:8095` with the actual URL of your Music Assistant instance.

import asyncio
from music_assistant_client import MusicAssistantClient
from music_assistant_client.exceptions import MusicAssistantError

async def main():
    # Replace with your Music Assistant server URL (e.g., http://192.168.1.100:8095)
    mass_client = MusicAssistantClient("http://localhost:8095")
    try:
        # Connect to the Music Assistant server
        await mass_client.connect()
        print(f"Connected to Music Assistant: {mass_client.server_info.server_version}")

        # Example: List available music providers
        providers = await mass_client.music.get_music_providers()
        print("\nMusic Providers:")
        for provider in providers:
            print(f"- {provider.name} (type: {provider.type.value})")

        # Example: Get all artists (might be large)
        # artists = await mass_client.music.get_all_artists()
        # print(f"\nTotal artists: {len(artists)}")

    except MusicAssistantError as e:
        print(f"Error connecting to Music Assistant: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")
    finally:
        # Ensure the connection is properly closed
        await mass_client.disconnect()

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →