{"id":9965,"library":"music-assistant-models","title":"Music Assistant Models","description":"The `music-assistant-models` library provides the core Pydantic V2 data models used across the Music Assistant ecosystem. It defines structured representations for media items (tracks, artists, albums), player states, queues, and other common entities. As of version 1.1.115, it requires Python 3.11+ and Pydantic V2. Releases typically follow the main Music Assistant project's development, with frequent updates to align with new features and data structures.","status":"active","version":"1.1.115","language":"en","source_language":"en","source_url":"https://github.com/music-assistant/models","tags":["music-assistant","models","pydantic","audio","media","data-structures","serialization"],"install":[{"cmd":"pip install music-assistant-models","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for defining all core data models (requires V2+).","package":"pydantic","optional":false},{"reason":"Efficient serialization/deserialization.","package":"msgspec","optional":false},{"reason":"Fast JSON serialization.","package":"orjson","optional":false},{"reason":"Semantic versioning utilities.","package":"semver","optional":false},{"reason":"Asynchronous operations timeout.","package":"async-timeout","optional":false}],"imports":[{"note":"Ensure to use 'music_assistant_models' as the top-level package, not 'music_assistant'.","wrong":"from music_assistant.models import Track","symbol":"Track","correct":"from music_assistant_models.metadata import Track"},{"note":"Models are organized into submodules like 'metadata', 'player', 'enums', etc.","wrong":"import Artist","symbol":"Artist","correct":"from music_assistant_models.metadata import Artist"},{"note":"Player-related models are found in the 'player' submodule.","wrong":"from music_assistant_models.models import PlayerState","symbol":"PlayerState","correct":"from music_assistant_models.player import PlayerState"},{"note":"Enums are grouped in the 'enums' submodule.","symbol":"EventType","correct":"from music_assistant_models.enums import EventType"}],"quickstart":{"code":"from music_assistant_models.metadata import Track, Artist, Album\nfrom music_assistant_models.enums import MediaType\nfrom music_assistant_models.player import PlayerState, RepeatMode\n\n# Example: Create a simple Artist object\nartist = Artist(\n    item_id=\"artist_123\",\n    provider=\"spotify\",\n    name=\"The Example Band\",\n    media_type=MediaType.ARTIST\n)\n\n# Example: Create an Album object\nalbum = Album(\n    item_id=\"album_456\",\n    provider=\"spotify\",\n    name=\"Greatest Hits\",\n    artists=[artist],\n    year=2023,\n    media_type=MediaType.ALBUM\n)\n\n# Example: Create a Track object\ntrack = Track(\n    item_id=\"track_789\",\n    provider=\"spotify\",\n    name=\"Sample Song\",\n    version=\"Original Mix\",\n    duration=240, # seconds\n    artists=[artist],\n    album=album,\n    media_type=MediaType.TRACK\n)\n\nprint(f\"Created Track: {track.name} by {', '.join(a.name for a in track.artists)}\")\nprint(f\"Track duration: {track.duration} seconds from album '{track.album.name}'\")\n\n# Accessing model attributes\nprint(f\"Track media type: {track.media_type.value}\")\n\n# Using other enums\nprint(f\"Current PlayerState options: {list(PlayerState)}\")\nprint(f\"Desired RepeatMode: {RepeatMode.ALL}\")\n\n# To serialize a model to JSON (Pydantic V2 style)\nimport json\nprint(\"\\nSerialized Track (JSON):\")\nprint(json.dumps(track.model_dump(), indent=2))\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your environment has Pydantic V2 installed by running `pip install 'pydantic>=2.0.0'`.","message":"`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.","severity":"breaking","affected_versions":"All 1.x versions"},{"fix":"Upgrade your Python environment to 3.11 or later. Consider using `pyenv` or `conda` to manage multiple Python versions.","message":"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.","severity":"breaking","affected_versions":"All 1.x versions"},{"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.","message":"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()`.","severity":"gotcha","affected_versions":"Users familiar with Pydantic V1 syntax"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Use the Pydantic V2 method `model_validate()` instead: `MyModel.model_validate(data_dict)`.","cause":"Attempting to use `parse_obj()` (a Pydantic V1 method) on a Pydantic V2 model when creating an instance from a dictionary.","error":"TypeError: 'dict' object is not callable"},{"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.","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.","error":"ImportError: cannot import name 'Track' from 'music_assistant_models.metadata'"},{"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`.","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.","error":"ERROR: Package 'music-assistant-models' requires a different Python: ..."}]}