music-assistant-server

1# CLAUDE.md
2
3Music Assistant is an async Python music library manager that connects to streaming services and speakers, integrating with Home Assistant.
4
5## Behaviour
6
7- NEVER automatically reply on Github (PR's or Discussions) without explicit consent from the developer.
8
9## Development Commands
10
11- `scripts/setup.sh` - Initial setup (venv, dependencies, pre-commit hooks). Re-run after pulling latest code.
12- `pytest` - Run all tests (add `-n auto --dist loadfile` to run in parallel)
13- `pytest --cov music_assistant` - Run all tests with coverage
14- `pytest tests/specific_test.py` - Run a specific test file
15- `pre-commit run --all-files` - Run all pre-commit hooks
16- `python -m music_assistant --log-level debug` - Run server locally (localhost:8095)
17- Requires ffmpeg v7.1+ and Python 3.14+ (see `.python-version` for the pinned runtime)
18
19Always run `pre-commit run --all-files` after a code change to ensure the new code adheres to the project standards.
20
21## Provider Development
22
23Providers are modular: music (sources), player (speakers), metadata (art/lyrics), plugin (extras). See `_demo_*_provider` directories for annotated templates when creating new providers.
24
25Each provider has at least `__init__.py` (logic) and `manifest.json` (metadata/config schema).
26
27Check `helpers/` for reusable utilities before writing new ones.
28
29## Code Style
30
31### Comments
32
33Only use comments to explain complex, multi-line blocks of code. Do not comment obvious operations. Inline comments in the code are there to explain code parts that need explaining, keep that in mind yourself when writing code but also respect existing comments from authors - they apparently had a reason to write the comment, dont remove them unless needed.
34
35### Docstring Format
36
37Use Sphinx-style docstrings with `:param:` syntax. For simple functions, a single-line docstring is fine.
38Don't explain inner workings of the code in the docstrings (you can use inline comments for that if/when needed). The docstring should provide clarity to the caller of the function/method, not explain how it works technically/internally. Use our preference for multi line docstrings where the first line starts on the next line:
39
40```python
41def my_function(param1: str, param2: int, param3: bool = False) -> str:
42    """
43    Brief one-line description of the function.
44
45    :param param1: Description of what param1 is used for.
46    :param param2: Description of what param2 is used for.
47    :param param3: Description of what param3 is used for.
48    """
49```
50
51Do **not** use Google-style (`Args:`) or bullet-style (`- param:`) docstrings.
52
53### File structure
54Private methods should be at the bottom of the file, public at the top.
55
56## Branching and PRs
57
58- All PRs target `dev` (primary development branch). `stable` is for production releases.
59- PRs labeled `bugfix` + `backport-to-stable` are automatically backported to `stable` — use only for bugs also present in `stable`.
60- Backporting a **schema change** permanently diverges `DB_SCHEMA_VERSION` between the branches and needs an extra dev-side guard migration; see `music_assistant/controllers/music/README.md`.
61
62## Debugging
63
64MA stores its data in `$HOME/.musicassistant/`. When debugging locally:
65
66- **Logs:** `$HOME/.musicassistant/musicassistant.log` (current), `musicassistant.log.1`, `.log.2`, etc. for older rotated logs.
67- **Database:** `$HOME/.musicassistant/library.db` — query via `sqlite3`. **Only execute SELECT queries** — never write to a live database.
68
69### Provider Mappings
70
71Every `MediaItem` (track, album, artist, playlist) has a `provider_mappings` attribute containing the exact mappings of the item on (each) provider. For a MediaItem that comes from a musicprovider directly, this will usually contain one single ID-mapping (although it is possible that a provider has multiple mappings). For library items, this will contain all mappings of all providers connected to the item.
72
73The ProviderMapping has this structure:
74
75- `item_id` (str): The music provider's item ID (e.g., `"spotify--track123"`)
76- `provider_domain` (str): The musicprovider's domain (e.g., `"spotify"`, `"apple_music"`, `"tidal"`)
77- `provider_instance` (str): The provider instance ID (to handle multiple instances of the same provider).
78- some more details such as the quality (relevant in case of album or track)
79
80**Important patterns:**
81
82- A media item itself also has an item_id and provider attribute. For an item that comes straight from the musicprovider itself (so not from the MA library) the provider attribute will be set to the instance_id of that provider.
83- Library items are identified by `item.provider == "library"` where `item.item_id` is the library DB ID
84- `provider_domain='library'` **never exists** in provider_mappings — library items don't have mappings to themselves
85- To resolve a provider item to its library equivalent, use: `await mass.music.<mediatype>.get_library_item_by_prov_id(item_id, provider_instance_id_or_domain)`
86- Never assume you can use `mapping.item_id` directly as a library DB ID — always use the resolution method above
87