tag-albums/README.md

# Tag albums

Tells Home Assistant which album to play when a vinyl record's RFID sticker (a **Tag**) is scanned, and provides a web page to give newly tagged records an album (an **Assignment**). See [CONTEXT.md](CONTEXT.md) for the vocabulary.

How it fits together:

1. The ESPHome RFID reader sends `tag_scanned` to Home Assistant, as before.
2. HA's `Play album by tag` script calls `POST /api/scans`. The service records the **Scan** and answers with the album, or `assigned: false`.
3. A tag the service hasn't seen before becomes an **Unassigned tag**. It appears on the web page within a few seconds, where you search the Music Assistant library and assign an album.
4. When the record is removed, HA's `Stop album by tag` script calls `GET /api/tags/{tag_id}`. It stops the player only if that tag has an album.

## Demo

A newly tagged record is scanned while the page is open, shows up under Unassigned tags, and gets an album from a live search of the Music Assistant library:

![Scanning a newly tagged record and assigning it an album](docs/assign-demo.gif)

## API

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", "albums": [{"artist", "album", "uri"}, …]}`, the albums in play order (empty when unassigned). Each `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 URIs unchecked. `404` if the tag has never been seen. |

Tag IDs are normalised to upper case.

A tag usually plays one album, but can play several in order, e.g. a vinyl that compiles two EPs the library has as separate releases. HA plays the first album (replacing the queue) and queues the others after it. On the web page, **Add** appends an album to a tag and **Assign** replaces all of them; the tag's page reorders and removes them.

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

Environment variables:

| Variable | Meaning |
|---|---|
| `API_TOKEN` | Shared secret Home Assistant sends in the `Authorization` header |
| `HA_URL` | Home Assistant base URL, e.g. `https://ha.home.knbg` |
| `HA_TOKEN` | HA long-lived access token, used to search the Music Assistant library |
| `DB_PATH` | SQLite file (default `tag_albums.sqlite3`); its directory must be writable |
| `MA_URL` | Optional. Address to download Music Assistant cover images from, e.g. `https://ma.home.knbg`, when Music Assistant's own address (`http://<host>:8095`) isn't reachable from the service. See [Album covers](#album-covers). |

HTTPS to HA is verified against the system trust store, so a home CA must be installed on the host. If it isn't, point `SSL_CERT_FILE` at the CA bundle.

## Development

```sh
uv sync
uv run pytest
API_TOKEN=dev HA_URL=https://ha.home.knbg HA_TOKEN=... uv run tag-albums serve --port 8087
```

## Running with Docker

For local testing. The container has to trust the home CA to reach HA, so mount the CA certificate and point `SSL_CERT_FILE` at it:

```sh
docker build -t tag-albums .
docker run --rm -p 8087:8087 -v tag-albums-data:/data \
  -e API_TOKEN=dev -e HA_URL=https://ha.home.knbg -e HA_TOKEN=... \
  -v /usr/local/share/ca-certificates/KNBG_Root_CA_306526670621344964268144771797781855543.crt:/ca.crt:ro \
  -e SSL_CERT_FILE=/ca.crt \
  tag-albums
```

To import assignments, run `tag-albums import-yaml` inside the container, e.g. `docker run --rm -v tag-albums-data:/data -v $PWD/tag_albums.yaml:/import.yaml:ro tag-albums tag-albums import-yaml /import.yaml`.

## Deploying in a FreeBSD jail

```sh
pkg install python313 py313-sqlite3 py313-uv git rust   # any Python >= 3.11; sqlite3 is a separate package
# uv compiles pydantic-core (Rust) and a few C extensions from source, since
# FreeBSD has no prebuilt wheels. The jail needs the base system's development
# files for that (e.g. /usr/lib/Scrt1.o, crti.o, libc): on a pkgbase jail,
# install the FreeBSD-*-dev packages (or the devel set) from the FreeBSD-base repo.
pw useradd tagalbums -d /nonexistent -s /usr/sbin/nologin
git clone <repo> /usr/local/tag-albums && cd /usr/local/tag-albums && uv sync --no-dev
install -d -o tagalbums /var/db/tag_albums

cat > /usr/local/etc/tag_albums.env <<'EOF'
API_TOKEN=<random, e.g. openssl rand -hex 32>
HA_URL=https://ha.home.knbg
HA_TOKEN=<HA long-lived token>
DB_PATH=/var/db/tag_albums/tag_albums.sqlite3
EOF
chmod 600 /usr/local/etc/tag_albums.env

install -m 755 deploy/rc.d/tag_albums /usr/local/etc/rc.d/tag_albums
sysrc tag_albums_enable=YES
service tag_albums start
```

Logs go to syslog with the tag `tag_albums`. The port defaults to 8087 (`sysrc tag_albums_port=...`).

### Importing the old tag_albums.yaml

One time, before switching Home Assistant over:

```sh
cd /usr/local/tag-albums
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'
```

### Linking assignments to the library

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 sync-library'
```

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):

```caddyfile
ma.home.knbg {
	@images path /imageproxy/*
	handle @images {
		reverse_proxy 172.16.40.250:8095
	}
	respond 404
}
```

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

```sh
cd /usr/local/tag-albums && git pull && uv sync --no-dev
service tag_albums restart
```

Database changes are applied automatically at startup.

## Home Assistant side

These pieces live in the `home-assistant-config` repo:

- `configuration.yaml`: two `rest_command`s, `tag_albums_scan` and `tag_albums_lookup`, pointing at `https://tag-albums.home.knbg` (a reverse proxy in front of port 8087). They set `verify_ssl: false`, because the certificate comes from the home CA and HA only trusts its built-in list of public CAs.
- `secrets.yaml`: `tag_albums_auth: "Bearer <API_TOKEN>"`.
- `scripts.yaml`: `play_album_by_tag` and `stop_album_by_tag` call those commands.

If the service is down, a scan plays nothing and `play_album_by_tag` writes a warning to the HA log.