music-assistant-home-assistant-addon

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
49**Examples**:
50
51```yaml
52# Use the dev branch (default)
53server_repo: dev
54
55# Use a specific branch
56server_repo: feature/new-player
57
58# Test a pull request
59server_repo: pr-456
60
61# Test a fork
62server_repo: someuser/server@experimental-feature
63
64# Use a specific commit
65server_repo: abc123def456...
66```
67
68**Default**: `dev` (uses `music-assistant/server@dev`)
69
70### Frontend Repository Configuration
71
72Use the `frontend_repo` option to specify which version of the Music Assistant frontend to install:
73
74**Format**: Same as server_repo - `owner/repo@reference` or just `reference`
75
76**Examples**:
77
78```yaml
79# Use the main branch (default)
80frontend_repo: main
81
82# Use a specific branch
83frontend_repo: feature/new-ui
84
85# Test a pull request
86frontend_repo: pr-789
87
88# Test a fork
89frontend_repo: someuser/frontend@redesign
90
91# Use a specific commit
92frontend_repo: abc123def456...
93```
94
95**Default**: `main` (uses `music-assistant/frontend@main`)
96
97## Full Configuration Example
98
99```yaml
100log_level: debug
101safe_mode: false
102server_repo: pr-456
103frontend_repo: someuser/frontend@custom-ui
104```
105
106This would test PR #456 of the server with a custom UI from a fork.
107
108## Important Notes
109
110### Build Time
111
112- The startup will take a while as the code needs to be built
113
114### Safe Mode
115
116- Set `safe_mode: true` if you need to start Music Assistant without loading providers
117- Useful for debugging any startup issues
118
119### Pull Request Syntax
120
121When 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.
122
123## Troubleshooting
124
125### Add-on won't start
126
1271. Check the add-on logs for build errors
1282. Verify the branch/PR/fork exists and is accessible
1293. Try using a known-good branch like `dev` or `main`
1304. Enable `safe_mode: true` to bypass provider loading
131
132### Build failures
133
134- Ensure the specified Git reference exists
135- Check if there are dependency conflicts in the branch
136- Frontend build requires Node.js - build failures may indicate incompatible frontend code
137
138### Performance issues
139
140- Building from source uses more resources
141- Only use this add-on for development testing, not as a daily driver
142
143## Developer Workflow
144
145### Testing a PR
146
1471. Find the PR number (e.g., #456)
1482. Configure: `server_repo: pr-456`
1493. Restart the add-on
1504. Test the changes
151
152### Developing Features
153
1541. Push your branch to your fork
1552. Configure: `server_repo: yourusername/server@your-branch`
1563. Restart the add-on
1574. Test and iterate
158
159### Testing Both Server and Frontend Changes
160
161```yaml
162server_repo: pr-456
163frontend_repo: pr-789
164```
165
166This allows you to test coordinated changes across both repositories.
167
168## Support
169
170This is a developer tool and is not supported for regular users. If you encounter issues:
171
172- Check the add-on logs
173- Verify your Git references are correct
174- Test with the default branches first
175- Ask in the Music Assistant developer Discord channel
176
177## Differences from Regular Add-on
178
179| Feature      | Regular Add-on    | DEV Add-on             |
180| ------------ | ----------------- | ---------------------- |
181| Installation | Pre-built release | Built from source      |
182| Startup time | Fast              | Slower (build time)    |
183| Stability    | Stable releases   | Development code       |
184| Updates      | Automatic         | Manual (change config) |
185| Use case     | Production        | Development/Testing    |
186