{"id":9963,"library":"music-assistant-client","title":"Music Assistant Client","description":"`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.","status":"active","version":"1.3.5","language":"en","source_language":"en","source_url":"https://github.com/music-assistant/music-assistant-client","tags":["api-client","music","async","audio","home-automation","streaming"],"install":[{"cmd":"pip install music-assistant-client","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Required for making asynchronous HTTP requests to the Music Assistant server.","package":"aiohttp","optional":false},{"reason":"Used internally for handling API rate limiting.","package":"asyncio-throttle","optional":false}],"imports":[{"note":"Python package names often convert hyphens to underscores for import paths. Do not use the hyphenated package name directly for imports.","wrong":"from musicassistantclient import MusicAssistantClient","symbol":"MusicAssistantClient","correct":"from music_assistant_client import MusicAssistantClient"},{"note":"Specific exceptions are found within the `exceptions` submodule.","symbol":"MusicAssistantError","correct":"from music_assistant_client.exceptions import MusicAssistantError"}],"quickstart":{"code":"import asyncio\nfrom music_assistant_client import MusicAssistantClient\nfrom music_assistant_client.exceptions import MusicAssistantError\n\nasync def main():\n    # Replace with your Music Assistant server URL (e.g., http://192.168.1.100:8095)\n    mass_client = MusicAssistantClient(\"http://localhost:8095\")\n    try:\n        # Connect to the Music Assistant server\n        await mass_client.connect()\n        print(f\"Connected to Music Assistant: {mass_client.server_info.server_version}\")\n\n        # Example: List available music providers\n        providers = await mass_client.music.get_music_providers()\n        print(\"\\nMusic Providers:\")\n        for provider in providers:\n            print(f\"- {provider.name} (type: {provider.type.value})\")\n\n        # Example: Get all artists (might be large)\n        # artists = await mass_client.music.get_all_artists()\n        # print(f\"\\nTotal artists: {len(artists)}\")\n\n    except MusicAssistantError as e:\n        print(f\"Error connecting to Music Assistant: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n    finally:\n        # Ensure the connection is properly closed\n        await mass_client.disconnect()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())","lang":"python","description":"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."},"warnings":[{"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()`).","message":"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.","severity":"breaking","affected_versions":"<1.0.0 to 1.x.x"},{"fix":"Always prepend `await` to any call that returns a coroutine (e.g., `await mass_client.connect()`, `await mass_client.music.get_music_providers()`).","message":"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.","severity":"gotcha","affected_versions":"All 1.x.x versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All 1.x.x versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install music-assistant-client` to install the library.","cause":"The `music-assistant-client` package is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'music_assistant_client'"},{"fix":"Ensure you are awaiting specific asynchronous methods, e.g., `await mass_client.connect()` or `await mass_client.music.get_all_artists()`.","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.","error":"TypeError: object MusicAssistantClient can't be used in 'await' expression"},{"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.","cause":"The Music Assistant server is not running, is inaccessible, or the specified host/port is incorrect. This is a network connection issue.","error":"aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host localhost:8095 ssl:False [Connection refused]"},{"fix":"Always call and `await` `mass_client.connect()` before attempting to use any other client methods.","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()`.","error":"AttributeError: 'MusicAssistantClient' object has no attribute 'music'"}]}