Music Assistant Models

Common errors

• TypeError: 'dict' object is not callable

  cause Attempting to use `parse_obj()` (a Pydantic V1 method) on a Pydantic V2 model when creating an instance from a dictionary.
  fix Use the Pydantic V2 method `model_validate()` instead: `MyModel.model_validate(data_dict)`.

• ImportError: cannot import name 'Track' from 'music_assistant_models.metadata'

  cause This error typically means the imported symbol (`Track`) does not exist in the specified module (`music_assistant_models.metadata`) or there's a typo in the module path.
  fix Double-check the exact spelling of the symbol and its correct submodule. Common submodules include `metadata`, `player`, `enums`, `errors`, `playlist`, `queue`, etc. Refer to the GitHub repository for the correct structure.

• ERROR: Package 'music-assistant-models' requires a different Python: ...

  cause You are trying to install `music-assistant-models` in a Python environment older than 3.11, which is explicitly not supported by the library.
  fix Create or activate a Python 3.11+ virtual environment, then attempt installation again. Example: `python3.11 -m venv .venv && source .venv/bin/activate && pip install music-assistant-models`.

Warnings

• breaking `music-assistant-models` specifically requires Pydantic V2 (>=2.0.0). Using Pydantic V1 will result in `ImportError` or `AttributeError` during model instantiation or method calls.
  Fix: Ensure your environment has Pydantic V2 installed by running `pip install 'pydantic>=2.0.0'`.
• breaking This library explicitly requires Python 3.11 or newer. Attempting to install or run on older Python versions (e.g., 3.10) will cause installation failures or runtime errors.
  Fix: Upgrade your Python environment to 3.11 or later. Consider using `pyenv` or `conda` to manage multiple Python versions.
• gotcha If you are migrating from Pydantic V1, be aware that many common methods have been renamed in V2. For example, `parse_obj` is now `model_validate`, `dict()` is `model_dump()`, and `json()` is `model_dump_json()`.
  Fix: Refer to the Pydantic V2 migration guide for a full list of method renames and API changes. Use `model_validate()` for creating models from dictionaries and `model_dump()`/`model_dump_json()` for serialization.

Install

• pip install music-assistant-models Install stable version

Imports

• Track
  wrong:

  from music_assistant.models import Track

  correct:

  from music_assistant_models.metadata import Track

  Ensure to use 'music_assistant_models' as the top-level package, not 'music_assistant'.
• Artist
  wrong:

  import Artist

  correct:

  from music_assistant_models.metadata import Artist

  Models are organized into submodules like 'metadata', 'player', 'enums', etc.
• PlayerState
  wrong:

  from music_assistant_models.models import PlayerState

  correct:

  from music_assistant_models.player import PlayerState

  Player-related models are found in the 'player' submodule.
• EventType

  from music_assistant_models.enums import EventType

  Enums are grouped in the 'enums' submodule.

Quickstart

This quickstart demonstrates how to import and instantiate core media item models like `Artist`, `Album`, and `Track`, as well as interacting with common enums. It highlights the use of Pydantic V2 methods for serialization.

from music_assistant_models.metadata import Track, Artist, Album
from music_assistant_models.enums import MediaType
from music_assistant_models.player import PlayerState, RepeatMode

# Example: Create a simple Artist object
artist = Artist(
    item_id="artist_123",
    provider="spotify",
    name="The Example Band",
    media_type=MediaType.ARTIST
)

# Example: Create an Album object
album = Album(
    item_id="album_456",
    provider="spotify",
    name="Greatest Hits",
    artists=[artist],
    year=2023,
    media_type=MediaType.ALBUM
)

# Example: Create a Track object
track = Track(
    item_id="track_789",
    provider="spotify",
    name="Sample Song",
    version="Original Mix",
    duration=240, # seconds
    artists=[artist],
    album=album,
    media_type=MediaType.TRACK
)

print(f"Created Track: {track.name} by {', '.join(a.name for a in track.artists)}")
print(f"Track duration: {track.duration} seconds from album '{track.album.name}'")

# Accessing model attributes
print(f"Track media type: {track.media_type.value}")

# Using other enums
print(f"Current PlayerState options: {list(PlayerState)}")
print(f"Desired RepeatMode: {RepeatMode.ALL}")

# To serialize a model to JSON (Pydantic V2 style)
import json
print("\nSerialized Track (JSON):")
print(json.dumps(track.model_dump(), indent=2))