music-assistant-server

1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4This guidance is aimed at Claude Code but may as well be suitable for other AI tooling, such as Github CoPilot.
5
6Instructions for an LLM (such as Claude) working with the code:
7
8- Take these instructions in mind
9- Look at existing provider implementations, type hints, docstrings and comments
10- Propose changes to extend this document with new learnings.
11
12
13## Project Overview
14
15Music Assistant is a (async) Python 3 based music library manager that connects to streaming services and supports various connected speakers. It's designed to run as a server on always-on devices and integrates with Home Assistant.
16
17## Development Commands
18
19### Setup and Dependencies
20- `scripts/setup.sh` - Initial development setup (creates venv, installs dependencies, configures pre-commit)
21- Always re-run after pulling latest code as requirements may change
22
23### Testing and Quality
24- `pytest` - Run all tests
25- `pytest tests/specific_test.py` - Run a specific test file
26- `pytest --cov music_assistant` - Run tests with coverage (configured in pyproject.toml)
27- `pre-commit run --all-files` - Run all pre-commit hooks
28
29Always run `pre-commit run --all-files` after a code change to ensure the new code adheres to the project standards.
30
31### Running the Server
32- Use F5 in VS Code to start Music Assistant locally (debug mode)
33- Or run from command line: `python -m music_assistant --log-level debug`
34- Server runs on `localhost:8095`
35- Entry point: `music_assistant.__main__:main`
36
37## Architecture
38
39### Core Components
40
411. **MusicAssistant (`music_assistant/mass.py`)** - Main orchestrator class
422. **Controllers (`music_assistant/controllers/`)** - Core functionality modules:
43   - `music.py` - Music library management and provider orchestration
44   - `players.py` - Player management and control
45   - `player_queues.py` - Playback queue management
46   - `streams.py` - Audio streaming logic
47   - `webserver.py` - Web API server
48   - `config.py` - Configuration management
49   - `cache.py` - Caching layer
50   - `metadata.py` - Metadata handling
51
523. **Models (`music_assistant/models/`)** - Base classes and interfaces:
53   - `core_controller.py` - Base class/model for all core controllers
54   - `music_provider.py` - Base for music providers
55   - `player.py` - Base for players (provided by player providers)
56   - `player_provider.py` - Base for player providers
57   - `plugin.py` - Plugin system base
58
594. **Providers (`music_assistant/providers/`)** - External service integrations:
60   - Music providers (Spotify, Apple Music, Tidal, etc.)
61   - Player providers (Sonos, Chromecast, AirPlay, etc.)
62   - Metadata providers (MusicBrainz, TheAudioDB, etc.)
63   - Plugin providers for additional functionality (such as spotify connect or lastfm scrobbling)
64
655. **Helpers (`music_assistant/helpers/`)** - Utility modules for common tasks
66
67### Provider Architecture
68
69Providers are modular components that extend Music Assistant's capabilities:
70
71- **Music Providers**: Add music sources (streaming services, local files)
72- **Player Providers**: Add playback targets (speakers, media players)
73- **Metadata Providers**: Add metadata sources (cover art, lyrics, etc.)
74- **Plugin Providers**: Add additional functionality
75
76Each provider has (at least):
77- `__init__.py` - Main provider logic
78- `manifest.json` - Provider metadata and configuration schema
79- many providers choose to split up the code into several smaller files for readability and maintenance.
80
81Template providers are available in `_demo_*_provider` directories.
82These demo/example implementations have a lot of docstrings and comments to help you setup a new provider.
83
84### Data Flow
85
861. **Music Library**: Controllers sync data from music providers to internal database
872. **Playback**: Stream controllers handle audio streaming to player providers
883. **Queue Management**: Player queues manage playback state and track progression
894. **Web API**: Webserver controller exposes REST API for frontend communication
90
91## Key Configuration
92
93- **Python**: 3.12+ required
94- **Dependencies**: Defined in `pyproject.toml`
95- **Database**: SQLite via aiosqlite
96- **Async**: Heavy use of asyncio throughout codebase
97- **External Dependencies**: ffmpeg (v6.1+), various provider-specific binaries
98
99## Development Notes
100
101- Uses ruff for linting/formatting (config in pyproject.toml)
102- Type checking with mypy (strict configuration)
103- Pre-commit hooks for code quality
104- Test framework: pytest with async support
105- Docker-based deployment (not standalone pip package)
106- VS Code launch configurations provided for debugging
107
108## Code Style Guidelines
109
110### Comments
111Use comments wisely. Only use comments to explain a complex, multi-line block of code.
112
113**❌ Bad example**
114```python
115# add 1 and 2 together
116add(1, 2)
117```
118
119**✅ Good example**
120```python
121# use xxx to achieve yyy
122..multi line code block of complex code
123```
124
125### Docstring Format
126
127Music Assistant uses **Sphinx-style docstrings** with `:param:` syntax for documenting function parameters. This is the standard format used throughout the codebase.
128
129**Correct format:**
130```python
131def my_function(param1: str, param2: int, param3: bool = False) -> str:
132    """Brief one-line description of the function.
133
134    Optional longer description providing more context about what the function does,
135    why it exists, and any important implementation details.
136
137    :param param1: Description of what param1 is used for.
138    :param param2: Description of what param2 is used for.
139    :param param3: Description of what param3 is used for.
140    """
141```
142
143**Key points:**
144- Use `:param param_name: description` format for all parameters
145- Brief summary on first line, followed by blank line
146- Optional detailed description before parameters section
147- No need to document types in docstring (use type hints instead)
148- No need to document return types in docstring (use type hints instead)
149
150**Incorrect formats to avoid:**
151```python
152# ❌ Bullet-style (being phased out)
153"""Function description.
154
155- param1: Description
156- param2: Description
157"""
158
159# ❌ Google-style
160"""Function description.
161
162Args:
163    param1: Description
164    param2: Description
165"""
166```
167
168**For simple functions**, a single-line docstring is acceptable:
169```python
170def get_item(self, item_id: str) -> Item:
171    """Get an item by its ID."""
172```
173
174**Enforcement:**
175- Ruff with pydocstyle rules enforces basic docstring structure
176- Pre-commit hooks check docstring format
177- The API documentation generator parses Sphinx-style docstrings for the web interface
178
179## Branching Strategy
180
181### Branch Structure
182- **`dev`** - Primary development branch, all PRs target this branch
183- **`stable`** - Stable release branch for production releases
184
185### Release Process
186- **Beta releases**: Released from `dev` branch on-demand when new features are stable
187- **Stable releases**: Released from `stable` branch on-demand
188- **Patch releases**: Cherry-picked from `dev` to `stable` (bugfixes only)
189
190### Versioning
191- **Beta versions**: Next minor version + beta number (e.g., `2.6.0b1`, `2.6.0b2`)
192- **Stable versions**: Standard semantic versioning (e.g., `2.5.5`)
193- **Patch versions**: Increment patch number (e.g., `2.5.5` → `2.5.6`)
194
195### PR Workflow
1961. Contributors create PRs against `dev`
1972. PRs are labeled with type: `bugfix`, `maintenance`, `new feature`, etc.
1983. PRs with `backport-to-stable` label are automatically backported to `stable`
199
200### Backport Criteria
201- **`backport-to-stable`**: Only for `bugfix` PRs that fix bugs also present in `stable`
202- **`bugfix`**: General bugfix label (may be for dev-only features)
203- Automated backport workflow creates patch release PRs to `stable`
204
205## Testing
206
207- Tests located in `tests/` directory
208- Fixtures for test data in `tests/fixtures/`
209- Provider-specific tests in `tests/providers/`
210- Uses pytest-aiohttp for async web testing
211- Syrupy for snapshot testing
212