Menu
Fetch unlinked ListenBrainz listens, search for MusicBrainz matches, evaluate with domain reasoning, and execute mappings / deletions with user approval.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | map-listens |
| description | Fetch unlinked ListenBrainz listens, search for MusicBrainz matches, evaluate with domain reasoning, and execute mappings / deletions with user approval. |
| disable-model-invocation | true |
Map unlinked ListenBrainz listens to MusicBrainz recordings for the user specified by LB_USER in .env.
/map-listens [count] — count defaults to 100.
Code runs via uv run from the repo root. CLI helpers in lb_mapper.cli:
fetch_listens — fetch recent listens, output unlinked as JSONsearch_batch — batch search LB Labs for recording matchesexecute — submit approved mappings and delete approved listensThe translation cache at ~/.cache/lb-mapper/translations.json is a flat JSON object keyed by either direction. Always write both directions when you learn an alias pair: cache["椎名林檎"] = "Sheena Ringo" and cache["Sheena Ringo"] = "椎名林檎". Lookup is cache.get(key). The cache grows across runs; later runs are faster.
Phase 1 Fetch unlinked listens
Phase 2 Translate CJK strings (both directions)
Phase 3 Search (primary + every recovery angle)
Phase 4 Evaluate matches
Phase 5 Reconcile verdicts (Case A/B + skip-recovery sweep)
Phase 6 Present for approval
Phase 7 Execute approved actions
All retry / recovery logic lives in the orchestration layer. The Python search_batch script is intentionally simple — it runs one primary query per item with one CJK-artist fallback. Anything beyond is the orchestrator's job.
uv run python -m lb_mapper.cli.fetch_listens COUNT
Paginates history until COUNT unlinked listens are collected. Outputs {total, linked, unlinked: [...]} on stdout. Each listen has listened_at, recording_msid, artist, track, release. Report totals to the user.
Load the cache. Use contains_cjk() from lb_mapper.lb_search to detect CJK / Hangul / Kana in artist and track.
For each CJK string, look up the cache; for misses, translate now. Strings fall into one of:
アルフレッド・ブレンデル → Alfred Brendel).Persist new entries to the cache in both directions when applicable.
Delegate bulk translation to Codex MCP and instruct it to use web search. Training-data recall produces plausible-sounding but wrong titles. Always verify via Apple Music JP / MusicBrainz / the artist's official discography page for: romaji ↔ native kanji inference, Apple Music JP Romaji - English title splits, well-known JP discography lookups, and classical work / catalog verification.
For every listen, gather candidates by trying all the angles below and merging the results. Don't stop after the first hit — fuzzy fallbacks look like matches but often aren't, so a real match found by a later angle wins.
echo '$JSON_ARRAY' | uv run python -m lb_mapper.cli.search_batch
Per item: {artist, track, release, original_artist} where artist / track are translated forms and original_artist is the original CJK if applicable. The script does one Typesense search per item plus one CJK-artist fallback. Returns {...input, results: [...]} per item.
Run proactively as a sibling to 3a. MB credits for Japanese acts are often indexed under native script only, so a Latin-form primary search may return nothing or — worse — return Typesense fallback hits that look like matches.
Trigger when:
Tokyo Incidents, Sheena Ringo, Maaya Sakamoto, Yoko Kanno, Mitsuki Takahata, Sakuzyo / Sakujo, Mika Kobayashi, Ryosuke Nagaoka, Ceui, SawanoHiroyuki[nZk], Yuki Kajiura, YOASOBI, Ado, Hikaru Utada, Hiroyuki Sawano, Promise of wizard).Romaji - English Translation (Apple Music JP convention). Split on -, use the romaji half for inference, discard the English (it rarely appears in MB).Search with (native_artist, native_track). If reverse translation is uncertain, delegate to Codex MCP with explicit web-search instruction. Persist new aliases in both directions.
When the artist field is a multi-artist credit (&, ,, feat.) and the primary returned zero or only fuzzy hits, re-search with just the first artist. This rescues classical recordings whose Typesense entry doesn't include the full "soloist, orchestra & conductor" string.
first = re.split(r'\s*[,&]\s*|\s+feat\.\s+', artist)[0].strip()
JP / anime scrobbles frequently shuffle primary vs featured artists relative to MB. For each feat. X in either field, run an LB Labs query with X as primary artist + the stripped track. Two patterns:
ペトロールズ — 雨 is indexed in MB as dropp — 雨 feat. ペトロールズ.削除 — 怪獣になりたい (feat. 初音ミク) is indexed as Sakuzyo feat. 初音ミク — 怪獣になりたい.Any retry whose artist_credit_name mentions the listen's primary artist (as either main or featured) is a valid candidate.
When 3a–3d still leave an item without a confident candidate (zero hits, or only fuzzy fallbacks where recording_name doesn't match the listen's track identity), query MB Lucene directly:
GET https://musicbrainz.org/ws/2/recording/?query=<lucene>&fmt=json&limit=10
User-Agent: lb-mapper/<version> (<contact>)
Strict 1 req / sec rate limit; sleep 1.05s between calls.
LB Labs Typesense and MB direct have very different recall. Many recordings exist in MB but never surface from Typesense; they surface immediately from the Lucene index.
artist:"<name>" — exact phrase. Prefer the form MB indexes under (Jan Lisiecki, not ヤン・リシエツキ; 椎名林檎, not Sheena Ringo).recording:<token> clauses joined with AND. Pick:
BWV 1001, K. 271, Op. 52, WoO 31).Fuga, Rondeau, Andantino).AND strictly — over-constrained queries return zero.Query priority order for items still missing after 3a–3d:
Sakuzyo).Mokuren → both 木蘭 and 木蓮).Listen titles carry decorations that don't appear in MB. Strip them so the AND-joined query matches:
(Remastered 2024), (Live), (feat. X), (Arr. ...), (TV Edit), (Extend ver.), [Deluxe].Op. 10: No. 1 in F-Sharp Minor → keep Op. 10 No. 1. Movement markers after the colon are phrased variably; narrow by catalog + ordinal, verify movement in post-check.recording:"No. 1" is too literal — use bare recording:op AND recording:10 AND recording:1.op. 10, Op. 10, Opus 10).score=100 is necessary but not sufficient — Lucene treats partial token matches as 100. Always verify the returned recording.title matches the listen's track identity using the Phase 4 rules. Common false hit: same artist + same opus number on a different opus + different movement.
Merge candidates from all angles, dedup by recording_mbid, preserve provenance (tag field: lb, lb-reverse, mb, 4a). MB-direct hits go to the top of the candidate list — far more selective than Typesense fallbacks.
For each listen, decide a verdict using the top ~5 candidates and the rules below. No hardcoded thresholds — apply the rules as reasoning steps. Batches ≥ 50 items: parallelize into ~100-item chunks across Codex MCP sessions or Claude Code subagents; each chunk writes [{idx, verdict, recording_mbid, reason}, ...]; merge by idx.
| Verdict | Meaning |
|---|---|
link | Confident match: same work, compatible artist, title identifies the same recording. |
review | Plausible but ambiguous: short title, larger ensemble credit, arrangement differences, partial title overlap. |
skip | No usable match — but the recording may still propagate to MB on a future sync. Default for native-script JP artists, non-classical katakana scrobbles, Latin-only with weak candidates. |
delete | The specific recording will not propagate. Triggers detailed under "CJK / katakana handling" below. |
The skip vs delete question is "will this specific recording propagate to MB on a future sync?" — not "does the artist have MB presence?". A famous artist's Apple-Music-JP exclusive may never appear in MB despite the artist having a rich MB catalog. The mainstream-artist heuristic protects only non-classical tracks (Case B default).
artist_credit_name must plausibly refer to the same artist(s) as the listen.&, ,, feat., and, vs, vs. are interchangeable. JP hardcore / dōjin scrobbles often render vs as &.Foster ≠ Neil Foster.feat. <listen_artist> inside the candidate's credit.Sakujo ≡ Sakuzyo, si ≡ shi, tu ≡ tsu, tyu ≡ chu.Alive, Home, Love, Shine) need stronger artist + release corroboration.(TV Edit), [Deluxe], (Arr. for Piano), (feat. X), (Live), (Remastered 20XX), (Recast 20XX), (Extend ver.), (Anime Ver.), (Transcr. for ...).Orchestral Version vs candidate Acoustic rejects.(Remastered 20XX) / (Recast 20XX) / (XX Edition) map to the original-recording MBID when no dedicated remaster MBID exists, provided artist + work + key + movement otherwise match.- (U+002D) ≡ ‐ (U+2010) ≡ ‒ ≡ –.(without vocals), (without 娘々), (instrumental), (off-vocal), (karaoke) match MB recordings tagged with the same kind of annotation.Mokuren → either 木蓮 or 木蘭). When this is the only difference and artist + release match, treat as a link.Classical titles encode precise work identity. Two recordings that share a generic word (Allegro, Sonata, Prelude) but differ in any of the following are different works:
No. 2 vs No. 1 in the same opus → different work.II. Allegro vs candidate III. Allegro giocoso is a mismatch.BWV 1178 vs candidate WoO 31) → reject even when artist matches.Cross-catalog equivalences: K. ≡ KV; nicknames ≡ formal titles (Moonlight Sonata ≡ Op. 27 No. 2; Für Elise ≡ Bagatelle WoO 59; Die Forelle ≡ The Trout, D. 550).
A katakana-only artist has a core name in pure katakana (transliterating a non-Japanese name). Standard kanji ensemble suffixes (四重奏団 quartet, 管弦楽団 orchestra, 室内管弦楽団 chamber orchestra, 交響楽団 symphony orchestra, 合唱団 choir) do not disqualify it.
Case A: katakana artist + classical track → delete when no candidate matches the work identity (catalog + movement + key) after Phase 3 has exhausted every angle. This applies even to mainstream classical artists. Apple Music JP / SmashTunes album-track scrobbles for any classical artist do not propagate to MB on later syncs.
Case B: katakana artist + non-classical track → skip by default. Promote to delete only when the title carries an explicit arrangement marker ((Arr. for ...), (Transcr. for ...), (After [Composer]'s [Work])) OR web search confirms a classical work behind a colloquial title, AND the verified-classical re-query also returns no MB match.
Native-script artist (kanji / hiragana) — never auto-delete; their recordings DO propagate. Verdict is skip when no match is found.
CJK-localized classical title on a non-katakana artist — delete when no candidate matches after title translation AND reverse-direction retry. If neither the English nor the native form finds the recording, it won't appear.
Mixed-script artists (katakana + Latin) — not auto-deleted; many have legitimate MB entries.
When deciding "no candidate survives", you must verify candidates against the track title, not just the artist. Typesense returns fuzzy fallback hits — any track by the artist whose title vaguely resembles the search. Always check recording_name matches the listen's track identity (work + catalog + movement + key).
Phase 4 evaluators (especially parallel chunks) are systematically biased toward skip and miss most Case A delete candidates and some recoverable links. The orchestrator owns the final boundary.
For each skip, promote to delete when all hold:
BWV, K., KV, Op., D., S., Hob., WoO, MWV, HWV, RV, TWV, Wq, Sz., L., FP, H., M., B., CD.Sonata, Concerto, Symphony, Prelude, Préludes, Fugue, Nocturne, Étude, Variations, Chaconne, Partita, Suite, Quartet, Quintet, Waltz, Scherzo, Mazurka, Ballade, Impromptu, Fantaisie, Fantasien, Intermezzo, Capriccio, Toccata, Rondo, Minuet, Polonaise, Cantata, Romance, Barcarolle, Bagatelle, Kinderszenen, Davidsbündlertänze, Stimmungsbilder, Bergamasque, Träumerei, Tombeau, Gymnopédie, Divertimento, Sinfonia.スラヴ行進曲 = Slavonic March, 朱色の塔 = Torre Bermeja).This is a regex match — be aggressive. Add new catalog markers and form words as you discover them.
For skip items where the artist is katakana-only and the track is non-classical-looking, delegate per-item web verification to Codex with explicit Use web search instruction. Classify each as classical / non-classical. For confirmed-classical items, re-query MB Lucene with the canonical composer + work. Promote to delete only when the work is verified-classical AND the MB re-query also fails.
skip for native-script (kanji / hiragana) artists — their specific recordings may still propagate.For every remaining skip whose Phase 3 candidates are Typesense fallbacks (top hit's recording_name doesn't match track_orig), run an MB-direct query using the priority order from Phase 3e. This is the highest-yield late-stage recovery — Phase 3e was invoked for items with zero Phase 3 hits, but listens with fuzzy fallbacks never reached it.
After the MB-direct query, if a clean match appears, promote skip → link. Persist any new aliases discovered (especially the EN ↔ native pair) to the cache in both directions.
Be conservative on demotion, aggressive on Case A promotion. Native-script artists with no MB match after the sweep stay skip — deletion is permanent and these artists' other recordings DO appear in MB.
Group by verdict. Never execute without explicit user approval.
Links (N items):
[artist] — [track]
-> [match_artist] — [match_title] ([recording_mbid])
Reviews (N items):
[artist] — [track]
-> [match_artist] — [match_title] ([recording_mbid])
Note: [reason for uncertainty]
Deletions (N items):
[artist] — [track] (listened_at: [timestamp])
Reason: [why this should be deleted]
Skips (N items): list briefly.
For groups > ~30 items, write the full detail to /tmp/review.md and show a summary + file path. Always show reviews and deletions inline — they require judgement.
User options: approve all · approve links only · approve links + deletions, defer reviews · cherry-pick by idx · override verdicts · re-evaluate specific items.
echo '{"mappings": [...], "deletions": [...]}' | uv run python -m lb_mapper.cli.execute
{recording_msid, recording_mbid}.{listened_at, recording_msid}.The script handles rate limits internally and reports per-action progress. A transient HTTP 500 on a deletion or mapping is non-fatal — retry once after a short delay.
recording_name against the listen's track identity.musicbrainz.org/ws/2/recording/) has strict 1 req/sec; sleep 1.05s between calls.X-RateLimit-Remaining; the Python client sleeps automatically.skip over delete. Deletion is irreversible.recording_mbid on non-link entries are valid — normalize before merging.