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### Docstring Format
111
112Music Assistant uses **Sphinx-style docstrings** with `:param:` syntax for documenting function parameters. This is the standard format used throughout the codebase.
113
114**Correct format:**
115```python
116def my_function(param1: str, param2: int, param3: bool = False) -> str:
117    """Brief one-line description of the function.
118
119    Optional longer description providing more context about what the function does,
120    why it exists, and any important implementation details.
121
122    :param param1: Description of what param1 is used for.
123    :param param2: Description of what param2 is used for.
124    :param param3: Description of what param3 is used for.
125    """
126```
127
128**Key points:**
129- Use `:param param_name: description` format for all parameters
130- Brief summary on first line, followed by blank line
131- Optional detailed description before parameters section
132- No need to document types in docstring (use type hints instead)
133- No need to document return types in docstring (use type hints instead)
134
135**Incorrect formats to avoid:**
136```python
137# ❌ Bullet-style (being phased out)
138"""Function description.
139
140- param1: Description
141- param2: Description
142"""
143
144# ❌ Google-style
145"""Function description.
146
147Args:
148    param1: Description
149    param2: Description
150"""
151```
152
153**For simple functions**, a single-line docstring is acceptable:
154```python
155def get_item(self, item_id: str) -> Item:
156    """Get an item by its ID."""
157```
158
159**Enforcement:**
160- Ruff with pydocstyle rules enforces basic docstring structure
161- Pre-commit hooks check docstring format
162- The API documentation generator parses Sphinx-style docstrings for the web interface
163
164## Branching Strategy
165
166### Branch Structure
167- **`dev`** - Primary development branch, all PRs target this branch
168- **`stable`** - Stable release branch for production releases
169
170### Release Process
171- **Beta releases**: Released from `dev` branch on-demand when new features are stable
172- **Stable releases**: Released from `stable` branch on-demand
173- **Patch releases**: Cherry-picked from `dev` to `stable` (bugfixes only)
174
175### Versioning
176- **Beta versions**: Next minor version + beta number (e.g., `2.6.0b1`, `2.6.0b2`)
177- **Stable versions**: Standard semantic versioning (e.g., `2.5.5`)
178- **Patch versions**: Increment patch number (e.g., `2.5.5` → `2.5.6`)
179
180### PR Workflow
1811. Contributors create PRs against `dev`
1822. PRs are labeled with type: `bugfix`, `maintenance`, `new feature`, etc.
1833. PRs with `backport-to-stable` label are automatically backported to `stable`
184
185### Backport Criteria
186- **`backport-to-stable`**: Only for `bugfix` PRs that fix bugs also present in `stable`
187- **`bugfix`**: General bugfix label (may be for dev-only features)
188- Automated backport workflow creates patch release PRs to `stable`
189
190## Testing
191
192- Tests located in `tests/` directory
193- Fixtures for test data in `tests/fixtures/`
194- Provider-specific tests in `tests/providers/`
195- Uses pytest-aiohttp for async web testing
196- Syrupy for snapshot testing
197