yonluandClaude Opus 5
e7748f1fd5
Plans 013 and 014, the album page that prompted them, and the smaller fixes they turned up. Changelog, largest first. ## The local library is shaped like files, not like MusicBrainz `audio_files` carries its own tags and points at `albums` and `artists`; `file_genres` is the one real many-to-many. `recordings`, `release_group_recordings`, `artist_credit`, `artist_credit_artist`, `recording_genres`, `release_groups` and `release_to_rg` are gone from the local side, and with them a six-way join in every read, a `MIN(release_group_id)` subquery in eleven queries and a first-credited-artist subquery in nine. Measured on a real 25,966-file library, every many-to-many that model expressed was 1:1 in the data. - Ownership is a file. `GetFilePathsByRecordingMBIDs`, `LibraryMBIDIndex.CheckMBIDs`, `collectLibraryEntities` and `pruneStaleLocalCrossReferences` all join `audio_files`, so the 812 orphaned recordings, 216 release groups and 260 artists that library carried are now structurally impossible. - One projection: every track query selects from the `track_metadata` view, one row type, one mapper. Nine hand-rolled copies had drifted far enough to report different years on different screens. - `library_id = 0` means every library, so each list query exists once instead of scoped and unscoped with a branch at every call site. - No migration chain. `sql/schemas/` is the one description of the shape; `sql/migrations/`, `applyMigrations` and `schema_migrations` are squashed away, along with the drift between them that had sqlc generating against a stale schema. - `database.InsertTestTrack` is the one test seeder; twenty test files had been assembling the old FK chain each in its own order. ## The catalog stores its ids as bytes `explore_index`'s three 36-char MBID columns and its entity-type text are 16 raw bytes and a small integer. The table and its six indexes go 780 MB to 405 MB on a real 2,052,200-row catalog, which is why a fresh install is ~0.6 GB rather than ~1.0 GB. - `backend/explore/mbid.go` is the only place the encoding is known; everything above it speaks dashed strings. - `CHECK(length(mbid) = 16)` makes a stringly write fail at the insert rather than silently returning no rows, since SQLite does not coerce between TEXT and BLOB. - The importer asks the artifact what encoding it carries and converts on the way in, so the artifact already published keeps working and no format bump is needed. - `indexRowColumns`/`scanIndexRow` replace four copies of a 22-column list, and `TestStoredEncodingRoundTrips` sweeps every read path. ## An album page that says how much of the album is yours - One question, asked once: is there a file. `filePaths` is filled by a single batched lookup when the tracklist settles, and the badge, the Play count, the dimmed rows and every menu item read it — replacing four claims of decreasing confidence that could show a green tick on an album whose every action did nothing. - Play, Play 7 of 12, or no play button at all. - `total_tracks` on `explore_index` (~2 bytes over 400,677 release groups) and on `audio_files` from tags that have always carried it: a complete MBID-matched album now makes no catalog call at all, where it used to spend the most expensive request the app makes. - A merged cluster shows the running order the most releases agree on, and the version list marks the release you own rather than standing a synthetic entry in for it. - `AlbumReleasesFailed`: a slow fetch is no longer reported as a failed one by a 12-second timer. - Rows not in the library are dimmed in place (with `aria-disabled`) instead of the owned ones wearing a green tick and a legend. ## Caches and cover art get ceilings - Only the three tiers of a cover are stored; the full-resolution copy nothing rendered was 1,134 MB of a 1.4 GB covers directory. - One artist portrait is downloaded and the rest are remembered as URLs — 4.1 GB of a 5.3 GB cache was candidates no code path reads. - `browsedArtBudget` and `httpCacheBudget` bound what an age cannot: the same install held art for 5,770 artists in a 1,301-artist library. - `OrphanedArtistImagesJob` joined a bare MBID onto a sharded directory, so it deleted the rows that were the only record of the files it left behind. `explore.ArtistImageDir` is that layout's one definition now. ## The autotag queue asks whether there is work `tagging_items` was a row per album folder, not a queue, and no query read the `tag_status` column that held the answer. The four queue queries ask the files, which matters most where it is least visible: `startPrefetch` was scoring every album in a tagged library against MusicBrainz. ## Phantom playlist tracks resolve in place An M3U8 imported before its files leaves phantom rows; they now match by path and fall back to position, keep their place in the playlist when resolved, and pair best-first so two phantoms cannot claim the same file. ## Playing a track plays the list it is in Double-click, and Play on a single row's menu, queue the list as displayed with `startIndex` on that row — the album page and the track list used to queue one track and discard the album around it. A multi-row selection still plays exactly itself. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AfVYUVExXsx1nSWrXN8mAh
3.7 KiB
The fixture library
test_data/music_library_test/ is generated, not committed:
make testdata (~1 s) builds 31 deterministic tracks across MP3, FLAC,
Ogg Vorbis and WAV. make testdata-force rebuilds unconditionally,
make testdata-clean deletes it. make test and make sandbox-seed
depend on it, so it is rarely run by hand.
Tests that need it fetch it through internal/testfixtures and skip
themselves when it has not been generated.
Select by case, never by path
m := testfixtures.Load(t)
paths := m.Case(t, testfixtures.CaseCoverDedup)
track := m.Track(t, rel)
Cases: cover-dedup, multi-disc, various-artists, flac-album,
ogg-album, wav-tracks, partial-tags, unicode, duplicates,
edge-lengths, broken.
Two invariants worth not breaking:
- The clean library is exactly 31 tracks, because
sandbox-seedverifies the scan against that count. Deliberately malformed files live in a sibling root,test_data/music_library_broken/(m.BrokenPath()), so the scanner never sees them. - Tags are written by
backend/tagwriter, not by ffmpeg (which encodes with-map_metadata -1). Fixture and reader therefore cannot drift into agreeing with each other and disagreeing with reality.
The manifest (test_data/music_library_test.manifest.json, outside the
scanned root) hashes the spec — paths, formats, durations, tags,
cover identity — not the bytes, because ffmpeg stamps encoder version
strings and identical specs produce different bytes on different builds.
In e2e specs
- Every fixture except one is 2–6 seconds. A spec that starts
playback and then clicks pause races the track ending and fails
against a correct UI. Use
LONG_TRACK(90 s,edge-lengths) exported frome2e/support/fixtures.ts. - WAV tracks scan in untitled.
backend/tagwriterwrites WAV tags into a RIFFid3chunk anddhowden/taghas no RIFF parser, so there is no "Field Recordings" artist in the Artists view. This is a known open bug pinned byTestWAVTagsAreNotReadableYet; do not "fix" a spec by asserting the broken behaviour elsewhere.
Seeds
make sandbox-seed NAME=default # build (boots a fresh YJ_HOME and drives the app)
make sandbox-seeds # list
make dev-headless SEED=default # restore into a run
A seed is a tarred YJ_HOME produced by running the app: fresh home →
real AddLibrary binding → poll until the real scan reports the
manifest's track count → SIGTERM so shutdown hooks persist state → tar.
Never hand-write one. Seeding points YJ_CORE_INDEX_URL at a dead
address on purpose, so no seed depends on what the explore artifact
server happened to be serving.
Rebuild a seed after any schema change. Nothing migrates a restored
database: applySchema is CREATE TABLE IF NOT EXISTS, so an old seed
keeps its old columns, the app starts, and the first query dies on
no such column.
Restoring the seed does not disable the artifact fetch — only
building it does. dev-headless leaves YJ_CORE_INDEX_URL alone,
so on a developer machine the restored app immediately downloads and
imports the real ~1.1M-row catalog, through the one writer connection,
while whatever you started it for is running. A full make e2e against
that reported 14 failures that were all contention; the same suite
against the same seed with
YJ_CORE_INDEX_URL='http://127.0.0.1:1/none.tar.zst' make dev-headless SEED=default
is the configuration CI runs (ci.yml sets exactly that address) and is
what to use before believing a failure. The tell is in .dev/app.log —
an import logging progress — and in how the failures look: timeouts
spread across unrelated specs rather than one surface being wrong.