Billboard Tag Plugin

Advanced Plugins
1

Billboard Tag

Tags your tracks with the Billboard charts they actually appeared on — matched against real chart history, not guesswork.

Description

Billboard Tag fills in your library’s Charts category tags (US Hot 100, Adult Contemporary, Alternative Airplay, and so on) automatically, based on whether a track genuinely charted. It’s a two-part system: a standalone Python tool does the heavy lifting, and this plugin applies the result inside Lexicon.

Why two parts? Billboard has no “what charts was this song on” API — the only way to know is to build an index of every charting song and match your library against it, which means scraping years of chart history and doing fuzzy artist/title matching. That’s real, occasionally slow work that doesn’t belong inside a blocking plugin action. So the Python side (source on GitHub) builds and maintains that index, matches it against your library, and writes a small queue file. This plugin reads that queue and does the part that actually belongs in Lexicon: writing tags through the documented _library API, with a real review step for anything uncertain.

What the plugin does, specifically:

  • One action, Review and Apply Billboard Tags, does a single pass over your library.
  • Exact matches (the track and Billboard’s own record agree after normalizing punctuation/features/etc.) get merged in automatically — no prompt, just written.
  • Fuzzy matches (a close-but-not-certain title/artist match) get a dialog each: artist, title, matched Billboard entry, confidence score, and which tag it would add. Submit to approve, Skip to pass.
  • Tags are always merged, never replaced — your existing genre/energy/mood tags are untouched, and a track’s apply history from the CLI’s plan CSV is respected the same way.
  • The plugin never creates or deletes tags. If a proposed tag doesn’t already exist in your Charts category, it’s left out — go create it in Lexicon first.

Scale note: this plugin is deliberately scoped to small, recurring batches — new tracks added since your last chart refresh, not a full library import. Auto-apply itself is uncapped (tested clean at 694 tracks in one run), but the review step is one blocking dialog per row with no save-and-resume, so it’s capped at 50 rows per run — past that, review is skipped for that run with a message pointing you at the companion CLI’s CSV-based workflow instead, while any auto-apply rows in the same batch still go through normally.

Setup, in short:

  1. Get the companion CLI running against your library (see the GitHub repo — it builds the chart index and does the matching).
  2. Install this plugin folder into Documents/Lexicon/Plugins/.
  3. Run python billboard_tag.py plan --plugin-out "<plugin folder>/Files/pending.json" on the machine with your chart index.
  4. Run Review and Apply Billboard Tags in Lexicon.
  5. To see what actually got written, run python view_changelog.py (also in the repo) — it opens a running log in your default text app. There’s deliberately no in-app changelog viewer; Lexicon’s dialog UI isn’t built for long scrollable content, so the plugin writes a plain-text log instead of trying to render one.

Settings

None. The plugin has no configurable settings — it’s entirely driven by pending.json, which the companion CLI generates.

Changelog

v1 — Initial release.

  • Review and Apply Billboard Tags: single-pass review + auto-apply, merge-only writes, batch-size guard on review only.
  • Persistent run history via a plain-text changelog.log, readable through the companion view_changelog.py script.

Download

Source and the companion CLI tool: github.com/sstrubberg/billboard-tag (public repo). The plugin itself lives in the lexicon-plugin/ folder — copy that folder into Documents/Lexicon/Plugins/ (not a symlink; Lexicon’s plugin scanner doesn’t follow those).