yellowjacket/.planning/plans/completed/015-multi-artist-credits.md

015 — Multi-artist credits, navigable

Completed. Phases 1, 2 and 4 shipped. Running the ingest against the real dump and publishing an artifact that carries credits is #88; Phase 3 (file_artists) is #89, blocked on it.

The problem

A track credited to more than one artist has exactly one navigable artist in this app, and the others are punctuation.

audio_files carries artist_credit (the credit as tagged, for display) and artist_id (one artist, for grouping and browsing). primaryArtist() (backend/library/artistcredit.go:53) resolves that one artist by string-parsing the credit: it strips a " feat. " clause, and deliberately does not split on &, x, with or , because those appear inside real artist names. So "Lana Del Rey ft. Sean Lennon" stores Lana Del Rey and discards Sean Lennon entirely, and "Alina Baraz & Galimatias" stores one artist whose name is the whole credit.

What the measurement says

Measured 2026-08-16 against a real 26,069-file library (19,840 mp3, 6,229 flac; 57 unreadable, m4a/ogg not examined), plus an 80+80 MusicBrainz inc=artist-credits sample.

• 13% of a random sample of the library's recordings have more than one credited artist in MusicBrainz (10 of 79 resolved). Extrapolates to ~3,250 of the 24,989 files carrying a recording MBID.
• 0.86% of files (224) carry any structured multi-artist signal in their own tags. mp3 carries zero files with multiple MUSICBRAINZ_ARTISTID values across 19,840 files; flac has 87.
• 1,286 files say "feat." in ARTIST; 1,159 of them (90%) have nothing structured behind it. A sample of 80 such files was multi-artist in MB 80 of 80 times.

CLAUDE.md currently justifies plan 013's removal of artist_credit / artist_credit_artist with "3 credits of 2,823 listed more than one artist". That figure measured our own writer, not the library: cachedLinkArtist was called exactly once per credit (e7748f1^:backend/library/library.go:1842), so a collaboration could never have been recorded, and the three were resolution collisions on shared credit text. Dropping the join table was still correct — it only ever held one row, so it was pure join cost — but the stated evidence does not support "multi-artist is rare". Correcting that claim is part of this plan.

Why the tags cannot answer it

Deriving the decomposition locally, with no network, works 79% of the time (169 of 215 files with a multi-value ARTISTS tag: mp3 69/105, flac 100/110), and the failures are systematic rather than random:

ARTIST  = '2Pac feat. Snoop Dogg, Nate Dogg, Hussein Fatal & Yaki Kadafi'
ARTISTS = ['2Pac', 'Snoop Doggy Dogg', 'Nate Dogg', 'Fatal', 'Yaki Kadafi']

ARTISTS holds canonical artist names; ARTIST holds as-credited names. Locating one inside the other fails on "Snoop Doggy Dogg" vs "Snoop Dogg", on "Fatal" vs "Hussein Fatal", and on Unicode (Michel'le vs Michel’le, K-Ci vs K‐Ci — U+2010, not a hyphen). That distinction is precisely what a join phrase encodes, and it is why this cannot be a tag-parsing feature.

Two format details that will mislead anyone re-running the probe: Picard writes ARTISTS slash-joined into one TXXX frame on mp3 and as true repeated Vorbis keys on flac, so a probe splitting only on NUL undercounts mp3 to zero.

The shape

MusicBrainz models a credit as ordered parts, and the credit string is derived from them — artist_credit.name is a cached render, nothing more. Each participant is (position, artist, name, join_phrase), where artist is the MBID (canonical, what you navigate to) and name is the credited spelling (what you display).

Join phrases are assembly instructions, not disassembly instructions. Rendering is a concatenation, never a search:

for each (position, artist_mbid, credited_name, join_phrase):
    emit link(credited_name -> artist_mbid)
    emit text(join_phrase)

The link positions are known by construction. This is load-bearing: if we instead located each credited_name inside the stored artist_credit text, we would reintroduce the mismatch above — the stored string may have come from the tags while the parts come from the catalog, and those disagree for ~1 in 3 multi-artist files (61 of 90 sampled credits rendered exactly equal to the tag string). Divergences seen: 'Skrillex feat. Swae Lee' tagged vs 'Skrillex & Swae Lee' in MB; 'STRFKR' vs 'Starfucker'; 'Zedd feat. Hayley Williams' vs '... of Paramore'. Either MB was edited after tagging or Picard versions differ; either way the search would miss or match the wrong span.

So audio_files.artist_credit stops being the source of truth and becomes the fallback, used only where there are no parts.

Where the data comes from

The catalog carries the decomposition; no user ever makes a per-recording call. Two sources were ruled out first, both cheaply:

• The canonical dump — which is what CI already pulls (dumpimport.go:84-85) — does not have it. canonical_musicbrainz_data.csv gives artist_mbids (ordered list) and artist_credit_name, but that last column is the rendered string. Splitting it on CI needs the as-credited names, so CI would fail exactly the way a local parse does.
• The JSON dumps do not cover the catalog. json-dumps/recording.tar.xz is 31 MB / 368 MB uncompressed and holds 153,691 recordings, not ~35M. Measured against the test library's 24,885 recording MBIDs: 0.00% overlap, zero rows. It is some other subset and is not usable.

That leaves the core dump, mbdump.tar.bz2 (7.1 GB compressed at the 20260815 export), from https://data.metabrainz.org/pub/musicbrainz/data/fullexport/. Four members are needed:

member	why	approx rows
mbdump/artist_credit_name	(artist_credit, position, artist, name, join_phrase) — the payload	~4M
mbdump/artist	id -> gid, since the above references artist row ids	~2.6M
mbdump/recording	gid -> artist_credit, to key credits by recording MBID	~35M
mbdump/release_group	same, for album credits	~2M

Coverage is not a concern

Of 24,885 distinct recording MBIDs in the test library, 24,808 (99.7%) already have an explore_index recording row, measured against a database at 2,052,200 rows — i.e. shipped-artifact coverage, not a local build's. The popularity filter does not strand the long tail here.

Status

• Phase 1 — done. backend/explore/dumpcredits.go + dumpcreditswrite.go, wired into dumpimport.go's run behind its own credits_import_done marker.
• Phase 2 — done. cmd/indexexport writes the two tables; artifactimport.go reads them behind artifactHasCredits().
• Phase 4 — done, and it does not need Phase 3. explore.GetCredits reads the catalog tables keyed on the recording MBID, which both sides of the app already carry — a catalog row has one and so does a local file (library.Track.RecordingMBID). So one binding serves the Explore pages and the library's own lists, and all ten artist-link call sites render credits today without a local table.
• Phase 3 (file_artists) — not started, and now an offline-resilience task rather than a prerequisite. The table is deliberately not declared yet: nothing writes or reads it, and a schema file plus a datamap note describing behaviour that does not exist is a claim the code cannot back. Its remaining value is that credits currently vanish when the catalog is absent or still downloading, which is precisely the no-index state ShelfPage.State exists to describe. Materialising into file_artists is what makes a library stand on its own.

Nothing renders yet in practice, because no published artifact carries credit tables — every credit falls back to its single link until an index build with Phase 1 runs and is exported.

Column layouts are verified against the real 20260815 export, not taken from the schema docs — artist(id, gid, …), artist_credit(id, name, artist_count, …), artist_credit_name(credit, position, artist, name, join_phrase) and recording(id, gid, name, artist_credit, …) were each read out of the dump. release_group shares recording's first four columns and is the one layout still taken on trust; ErrDumpShape turns a wrong guess into a loud failure rather than a quietly wrong catalog.

Still unrun: the ingest against the real 7.1 GB dump. Everything is covered by tests over a synthetic tar, which cannot catch a surprise in the other ~35M rows.

Phase 1 — Ingest credits on CI

New dump stage in cmd/indexbuild, behind the indexbuild tag with the rest of dumpimport.go's stages.

Constraint from b98840e: cmd/indexbuild is built CGO_ENABLED=0 in a plain golang container and must not reach the Wails application package — TestIndexToolsDoNotImportWails walks go list -deps -tags indexbuild. Nothing here should need it, but a new ServiceStartup hook on a package this imports is how it comes back. Go's compress/bzip2 is pure Go and decompress-only, which is all this needs.

Measured, 20260815 export. Tar members are alphabetical, and that is favourable: artist (435 MB), artist_credit (414 MB) and artist_credit_name (237 MB) all fall inside the first ~900 MB compressed, while recording and release_group come later. So the maps are complete before the rows that consume them arrive, and no recording data is ever buffered.

Pure-Go compress/bzip2 decompresses at 26 MB/s uncompressed / 8.7 MB/s compressed (measured on a 250 MB prefix, 3.01x ratio) — ~13.7 min for the whole file single-threaded, and less because the stream can stop after release_group rather than reading the series/tag/track/url/work tail. The 2 MB/s origin throttle dominates, as it already does for every other dump here.

Do not, however, depend on the ordering: assert it and fall back to buffering if a future export reorders, rather than silently emitting nothing.

• artist -> map[int32]uuid16 (~2.6M x ~20 B = ~60 MB)
• artist_credit_name -> map[int32][]creditPart (~4M x ~40 B = ~200 MB)
• recording / release_group -> emit gid -> credit_id only for MBIDs already in explore_index (the kept set is ~1.4M x 16 B = ~22 MB), which is what keeps 35M rows from being held

Peak ~300 MB, one sequential pass.

Only multi-artist credits are stored. A single-artist credit is (name, "") and is already fully described by explore_index's artist_name / artist_mbid; storing it would triple the table for nothing. Post-filter after loading, once the row count per credit is known.

New tables (and datamap entries, or TestCatalogCoversSchema fails the build — both are Cache, matching explore_index):

artist_credit_part(credit_id, position, artist_mbid, credited_name, join_phrase)

with explore_index.artist_credit_id as the link. Credits are shared — an album's twelve tracks by one artist share one credit row — which is the opposite of 013's local verdict, and correctly so: 1:1 in a local library, genuinely many-to-one at 2M-row catalog scale.

Phase 2 — Ship them in the artifact

cmd/indexexport currently creates exactly two tables in the artifact (explore_index, artifact_meta, at cmd/indexexport/*.go:147,170), so this is a structural addition, not a column.

Estimated size: ~13% of 1.4M recordings, deduplicated by shared credit, at ~2.3 parts each — order 400k rows, ~18 MB uncompressed. Against a ~0.6 GB install that is acceptable; it must be measured rather than assumed before merge.

artifactimport.go must read it only if present, on the writer handle where core is attached — the artifactHasTotals() / artifactStoresText() pattern (artifactimport.go:145-175), one step up from a column to a table. An artifact published before this exists is still a perfectly good catalog and must import as one that declines to answer. Adding this to the importer's SELECT list without the probe is how every already-published artifact starts failing.

artifactCatalogColumns gains artist_credit_id; it is kept in sync with the exporter by TestArtifactColumnsMatchExporter.

Phase 3 — Materialize locally

file_artists(audio_file_id, position, artist_id, credited_name, join_phrase)

credited_name is stored per row, not looked up from artists.name — that is the Snoop-Doggy-Dogg distinction, and it is the whole point.

Filled at scan/import time by joining audio_files.recording_mbid against the catalog. Materialized rather than resolved live, because the catalog is a downloaded artifact that can be absent or still arriving — that is why ShelfPage.State has a no-index value — and a library whose track rows lose their artists when the catalog is missing is worse than today.

That implies a backfill for the case where the catalog arrives after the library was scanned. It registers with jobs (progress, cancel) like every other long pass, and takes a distinct kind from index-build, since job-controls.ts keys its "you will discard hours of downloading" confirmation on that kind.

artists gains rows for guests who own no files. This changes what the artists grid shows and is an open question below.

Phase 4 — Render

utils/explore-link.ts gains a credit-rendering entry point taking ordered parts and returning a TemplateResult. Every row and detail view already renders artist names through it, so they inherit multi-artist links without individually knowing credits exist — the property that made centralising it worthwhile.

Its existing fallback philosophy already covers the no-parts case: "a list where some rows are clickable and others silently are not reads as a bug, not as a statement about metadata." Where there are no parts (no recording MBID, or no catalog row — ~4% of the test library) render today's behaviour: the flat artist_credit string with one link to the primary artist. Do not split the string there. There is genuinely no information to split on, and that is the one place the temptation returns.

primaryArtist() stays exactly as it is. It remains the fallback and is still what artist_id means.

Open questions

1. Catalog credit vs tagged credit, when they disagree (~1 in 3 multi-artist files). Rendering the catalog's decomposition is what makes names navigable; preserving the file's is what makes the app reflect the user's files. Leaning toward: render the catalog decomposition, keep artist_credit as the fallback string. Wants a deliberate decision, not an accident.
2. Do guest artists appear in the artists grid? Phase 3 creates artists rows for people who own no files. The grid currently means "artists in your library" and joins audio_files. A guest on one track is arguably in the library and arguably not. Whichever way, the ownership question stays "is there a file" — that rule does not bend.
3. release_group credits are ingested in the same pass for nearly nothing, but album-artist rendering is a separate surface. Ship the data in phase 1, render in a follow-up rather than widening phase 4.
4. Our own tagwriter does not write ARTISTS or multiple MUSICBRAINZ_ARTISTID frames, so autotagging a folder degrades the very field this rests on — the same shape as the existing track-totals note. Out of scope here; worth recording.

Verification

• Coverage: re-run the library probe and assert file_artists is populated for ~13% of files, not ~0.9%.
• TestCatalogCoversSchema / TestLifetimesMatchSchema for the new tables.
• TestIndexToolsDoNotImportWails still passes with the new stage.
• An artifact without the credits table imports cleanly (the artifactHasTotals regression shape).
• Round-trip: a known multi-artist recording renders each name as a separate link with the correct join phrases between them.