/
/
/
1# Music Assistant DEV Add-on
2
3This is a special development add-on for Music Assistant that allows developers to quickly test specific branches, pull requests, or even forks of Music Assistant directly in Home Assistant.
4
5## Purpose
6
7This add-on is designed for:
8
9- Testing pull requests before merging
10- Developing and debugging new features
11- Testing forks of Music Assistant
12- Running custom branches for testing
13
14## How It Works
15
16Unlike the regular Music Assistant add-on which uses pre-built releases, this dev add-on:
17
181. Builds and installs the server from a specified Git source (branch, PR, or fork)
192. Builds and installs the frontend from a specified Git source (branch, PR, or fork)
203. Starts Music Assistant with your custom code
21
22The build process:
23
241. Installs the server package from the specified Git reference
252. Builds the frontend according to its build procedure (npm build)
263. Installs the frontend as a Python package (overwriting the default frontend)
274. Starts Music Assistant
28
29## Configuration
30
31### Basic Configuration
32
33```yaml
34log_level: info
35safe_mode: false
36```
37
38### Server Repository Configuration
39
40Use the `server_repo` option to specify which version of the Music Assistant server to install:
41
42**Format**: `owner/repo@reference` or just `reference`
43
44- **Branch**: `dev`, `main`, or any branch name
45- **Pull Request**: `pr-123` (will checkout PR #123)
46- **Fork**: `username/server@branch-name`
47- **Commit**: Full commit SHA
48- **Empty/blank**: Use latest nightly release from GitHub (fast mode - no build required)
49
50**Examples**:
51
52```yaml
53# Use latest nightly release (FAST - no build required)
54server_repo: ""
55
56# Use the dev branch
57server_repo: dev
58
59# Use a specific branch
60server_repo: feature/new-player
61
62# Test a pull request
63server_repo: pr-456
64
65# Test a fork
66server_repo: someuser/server@experimental-feature
67
68# Use a specific commit
69server_repo: abc123def456...
70```
71
72**Default**: `""` (empty - uses latest nightly release from GitHub)
73
74> **Note**: When `server_repo` is left empty or blank, the add-on will install the latest nightly release wheel from GitHub releases. This is the fastest option as no server build is required.
75
76### Frontend Repository Configuration
77
78Use the `frontend_repo` option to specify which version of the Music Assistant frontend to install:
79
80**Format**: Same as server_repo - `owner/repo@reference` or just `reference`
81
82- **Branch**: `main`, `dev`, or any branch name
83- **Pull Request**: `pr-789` (will checkout PR #789)
84- **Fork**: `username/frontend@branch-name`
85- **Commit**: Full commit SHA
86- **Empty/blank**: Skip frontend build (use bundled frontend)
87
88**Examples**:
89
90```yaml
91# Skip frontend build (FAST - use bundled frontend)
92frontend_repo: ""
93
94# Use the main branch
95frontend_repo: main
96
97# Use a specific branch
98frontend_repo: feature/new-ui
99
100# Test a pull request
101frontend_repo: pr-789
102
103# Test a fork
104frontend_repo: someuser/frontend@redesign
105
106# Use a specific commit
107frontend_repo: abc123def456...
108```
109
110**Default**: `""` (empty - uses bundled frontend, no build)
111
112> **Note**: When `frontend_repo` is left empty or blank, the frontend build will be **skipped entirely**. This significantly reduces startup time and is ideal when you only need to test backend features. The frontend bundled with the server installation will be used instead.
113
114## Full Configuration Examples
115
116### Fast Mode (Backend Testing Only)
117```yaml
118log_level: info
119safe_mode: false
120server_repo: ""
121frontend_repo: ""
122```
123Uses latest nightly release from GitHub, no builds required. Fastest startup time.
124
125### Backend Development Mode
126```yaml
127log_level: debug
128safe_mode: false
129server_repo: dev
130frontend_repo: ""
131```
132Builds server from the `dev` branch, skips frontend build. Good for testing backend changes quickly.
133
134### Full Development Mode
135```yaml
136log_level: debug
137safe_mode: false
138server_repo: pr-456
139frontend_repo: pr-789
140```
141Builds both server (PR #456) and frontend (PR #789) from source. Full control for comprehensive testing.
142
143## Important Notes
144
145### Build Time
146
147Build time varies depending on your configuration:
148- **Both empty** (`server_repo: ""` and `frontend_repo: ""`): Fastest - no builds, uses latest nightly release
149- **Only `server_repo` specified**: Medium - builds server only, skips frontend (ideal for backend testing)
150- **Both specified**: Slowest - builds both server and frontend from source (full development mode)
151
152**Tip**: Leave `frontend_repo` empty when only testing backend features to significantly reduce startup time!
153
154### Safe Mode
155
156- Set `safe_mode: true` if you need to start Music Assistant without loading providers
157- Useful for debugging any startup issues
158
159### Pull Request Syntax
160
161When specifying a pull request, use `pr-NUMBER` (e.g., `pr-123`, `pr-456`). The add-on will automatically fetch and checkout the PR for you.
162
163## Troubleshooting
164
165### Add-on won't start
166
1671. Check the add-on logs for build errors
1682. Verify the branch/PR/fork exists and is accessible
1693. Try using a known-good branch like `dev` or `main`
1704. Enable `safe_mode: true` to bypass provider loading
171
172### Build failures
173
174- Ensure the specified Git reference exists
175- Check if there are dependency conflicts in the branch
176- Frontend build requires Node.js - build failures may indicate incompatible frontend code
177
178### Performance issues
179
180- Building from source uses more resources
181- Only use this add-on for development testing, not as a daily driver
182
183## Developer Workflow
184
185### Testing a PR
186
1871. Find the PR number (e.g., #456)
1882. Configure: `server_repo: pr-456`
1893. Restart the add-on
1904. Test the changes
191
192### Developing Features
193
1941. Push your branch to your fork
1952. Configure: `server_repo: yourusername/server@your-branch`
1963. Restart the add-on
1974. Test and iterate
198
199### Testing Both Server and Frontend Changes
200
201```yaml
202server_repo: pr-456
203frontend_repo: pr-789
204```
205
206This allows you to test coordinated changes across both repositories.
207
208## Support
209
210This is a developer tool and is not supported for regular users. If you encounter issues:
211
212- Check the add-on logs
213- Verify your Git references are correct
214- Test with the default branches first
215- Ask in the Music Assistant developer Discord channel
216
217## Differences from Regular Add-on
218
219| Feature | Regular Add-on | DEV Add-on (Nightly mode) | DEV Add-on (Source mode) |
220| ------------ | ----------------- | ------------------------- | ------------------------ |
221| Installation | Pre-built release | Latest nightly wheel | Built from source |
222| Startup time | Fast | Fast | Slower (build time) |
223| Stability | Stable releases | Nightly builds | Development code |
224| Frontend | Bundled | Bundled | Built from source |
225| Updates | Automatic | Manual (restart) | Manual (change config) |
226| Use case | Production | Quick backend testing | Full development/testing |
227
228**Configuration Modes:**
229- **Fast mode**: Both repos empty - Uses latest nightly release, no builds
230- **Backend dev mode**: Only `server_repo` specified - Builds server, uses bundled frontend
231- **Full dev mode**: Both repos specified - Builds everything from source
232