twisla/tag-albums
Public Access
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Play albums by their Music Assistant URI

Browse Source 
Names can match near-duplicate library albums that differ only in capitals (Let the/The Tribe Increase), and Music Assistant picked the unplayable one. Assignments now store the album's library URI, scans return it after checking it's still in the library (re-finding it by name, exact spelling first, if not), and HA plays by it. sync-library (formerly fetch-covers) links existing assignments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
twisla
2026-09-26 00:23:54 +00:00
co-authored by Claude Opus 5.5
parent 91e4519503
commit a2f421c272
8 changed files with 217 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+13 -7
View File
@@ -21,11 +21,13 @@ Both endpoints need `Authorization: Bearer <API_TOKEN>`.
| Endpoint | Purpose |
|---|---|
| `POST /api/scans` `{"tag_id": "53-13-0B-2A"}` | Record a Scan; creates the Tag on first sight. Returns `{"tag_id", "assigned": true, "artist", "album"}` or `{"tag_id", "assigned": false}`. |
| `GET /api/tags/{tag_id}` | Read-only lookup, same response. `404` if the tag has never been seen. |
| `POST /api/scans` `{"tag_id": "53-13-0B-2A"}` | Record a Scan; creates the Tag on first sight. Returns `{"tag_id", "assigned": true, "artist", "album", "uri"}` or `{"tag_id", "assigned": false}`. `uri` is the album's Music Assistant URI (e.g. `library://album/2846`), checked against the library on every scan; `null` means play by name. |
| `GET /api/tags/{tag_id}` | Read-only lookup, same response, with the stored `uri` unchecked. `404` if the tag has never been seen. |
Tag IDs are normalised to upper case.
HA plays by `uri` when there is one, because a library can hold near-duplicate albums whose names differ only in capitals, and only one of them may be playable. On each scan the service checks the stored URI is still in the library. If it's gone (e.g. after a library rebuild), it finds the album by name again, preferring the exact spelling, and stores the new URI.
The web page (`/`) has no login: keep the service on the LAN.
## Configuration
@@ -102,16 +104,20 @@ env DB_PATH=/var/db/tag_albums/tag_albums.sqlite3 \
su -m tagalbums -c '.venv/bin/tag-albums import-yaml /path/to/tag_albums.yaml'
```
### Album covers
### Linking assignments to the library
The service stores each assignment's cover and serves it itself. Music Assistant's image URLs are plain http on another host, which browsers block on an https page. Albums assigned from the web page get their cover right away. Imported assignments have none, so fetch them once (this reads the env file for HA access):
Albums assigned from the web page store their library URI and cover straight away. Imported assignments only have names, so link them once. This finds each album (exact spelling first), stores its URI and downloads its cover. It reads the env file for HA access:
```sh
cd /usr/local/tag-albums
su -m tagalbums -c 'set -a; . /usr/local/etc/tag_albums.env; set +a; .venv/bin/tag-albums fetch-covers'
su -m tagalbums -c 'set -a; . /usr/local/etc/tag_albums.env; set +a; .venv/bin/tag-albums sync-library'
```
It lists the albums Music Assistant has no cover for; those keep the grey placeholder. Running it again only looks at assignments still missing a cover.
It lists albums it couldn't find (those keep playing by name) and albums with no cover in Music Assistant. Running it again only looks at assignments still missing something. `fetch-covers` is an older name for the same command. Scanning an assignment without a URI also links it.
### Album covers
The service stores each assignment's cover and serves it itself. Music Assistant's image URLs are plain http on another host, which browsers block on an https page. `sync-library` (above) fetches covers for imported assignments; albums with no cover in Music Assistant keep the grey placeholder.
The service downloads covers from the address Music Assistant reports: its own host and port 8095, over plain http. If the jail can't reach that, put Music Assistant's image proxy behind the reverse proxy and set `MA_URL` to it. For example, in Caddy (use the same TLS setup as your other sites):
@@ -125,7 +131,7 @@ ma.home.knbg {
}
```
Then add `MA_URL=https://ma.home.knbg` to the env file and restart the service. Only `/imageproxy/*` is exposed, not the Music Assistant interface. If `fetch-covers` can't connect, it stops at the first cover and says so.
Then add `MA_URL=https://ma.home.knbg` to the env file and restart the service. Only `/imageproxy/*` is exposed, not the Music Assistant interface. If `sync-library` can't connect, it stops at the first cover and says so.
### Updating