feat: mood playlists from Last.fm crowd tags

A second set of playlists selecting by genre and mood rather than by play
history: eighties synths, high energy rock, screamo, drum and bass, dance,
classic rock.

The tags come from Last.fm rather than MusicBrainz. MusicBrainz genres arrive
free with the Lidarr index, which makes them the obvious choice and the wrong
one: they are sparse and formal, and will not tell you a record is screamo or
synthwave. Crowd tags will, because people typed them.

One request per artist, by MusicBrainz id where Lidarr has one, refreshed every
ninety days. An artist Last.fm has never heard of is recorded as fetched with no
tags rather than left unmarked, so it is not asked about again on every pass
forever. The tag table is keyed on the normalised artist name, not the Lidarr
id, so it survives an artist being removed and re-added there.

Weights are taken from the response's count where it has one. The documented
sample carries only a name and a URL, a live response also carries a 0-100
count, and depending on either alone would be a guess -- so the count is used
when present and the documented ordering by popularity stands in when it is not.

An artist qualifies for a mood when their weights inside it sum to at least
thirty. A single low-weight tag is not a genre, it is somebody's stray opinion.
A mood may also restrict release years, which is what separates eighties synth
records from everything else a synthpop tag drags in.

The built-in set is chosen for this library rather than as a taxonomy, and
--vibes replaces it wholesale with a JSON file so a new mood does not need a new
release. Names are validated when that file is read: an invalid one would
otherwise only surface as a playlist written somewhere unintended.

music_curator.py

@@ -69,6 +69,18 @@ BACKOFF_CEILING_SECONDS = 60.0
 MIRROR_SUFFIX = ".mp3"
 PLAYLIST_DIRECTORY = "_playlists"
 
+# Tags are re-fetched this often. They move slowly, and the first pass over a
+# library already costs one request per artist.
+TAG_REFRESH_SECONDS = 90 * 86400
+
+# How much of an artist's tag weight has to fall inside a vibe before their
+# tracks are eligible for it. Weights are Last.fm's own 0-100 popularity, summed
+# across whichever of the vibe's tags the artist carries.
+VIBE_MIN_SCORE = 30
+
+# A vibe writes a file named after itself, so the name has to be a filename.
+SAFE_VIBE_NAME = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+
 # Group-readable, for the same reason music-mirror sets it: the mirror is read
 # back by whatever serves it, and a playlist nobody can read is not a playlist.
 GROUP_READ = 0o040
@@ -177,6 +189,24 @@ CREATE TABLE IF NOT EXISTS scrobble_key (
     PRIMARY KEY (artist, track)
 );
 CREATE INDEX IF NOT EXISTS scrobble_key_track ON scrobble_key (track_id);
+
+-- Last.fm's crowd tags for each library artist. MusicBrainz genres come free
+-- with the Lidarr index and are useless for this: they are sparse and formal,
+-- and will not tell you a record is screamo or synthwave. People typing tags
+-- will. Keyed on the normalised name rather than the Lidarr id so it survives
+-- an artist being removed and re-added there.
+CREATE TABLE IF NOT EXISTS artist_tag (
+    norm_artist TEXT    NOT NULL,
+    tag         TEXT    NOT NULL,
+    weight      INTEGER NOT NULL,
+    PRIMARY KEY (norm_artist, tag)
+);
+CREATE INDEX IF NOT EXISTS artist_tag_tag ON artist_tag (tag);
+
+CREATE TABLE IF NOT EXISTS artist_tag_fetched (
+    norm_artist TEXT PRIMARY KEY,
+    fetched_at  INTEGER NOT NULL
+);
 """
 
 
@@ -546,6 +576,24 @@ class Store:
                 tracks,
             )
 
+    def replace_tags(self, norm_artist, pairs, now):
+        """Replace one artist's tags, and record that they were fetched.
+
+        The fetch is recorded even when nothing came back, so an artist Last.fm
+        has never heard of is not asked about again on every pass.
+        """
+        with self.connection:
+            self.connection.execute("DELETE FROM artist_tag WHERE norm_artist = ?", (norm_artist,))
+            self.connection.executemany(
+                "INSERT OR IGNORE INTO artist_tag (norm_artist, tag, weight) VALUES (?, ?, ?)",
+                [(norm_artist, tag, weight) for tag, weight in pairs],
+            )
+            self.connection.execute(
+                "INSERT INTO artist_tag_fetched (norm_artist, fetched_at) VALUES (?, ?)"
+                " ON CONFLICT (norm_artist) DO UPDATE SET fetched_at = excluded.fetched_at",
+                (norm_artist, now),
+            )
+
     def rebuild_keys(self):
         """Collapse the scrobble history into one row per distinct track.
 
@@ -1177,6 +1225,200 @@ PLAYLISTS = (
 )
 
 
+# Moods, as sets of Last.fm tags. Chosen for this library -- drum and bass,
+# punk and its descendants, big-room dance, classic rock -- rather than as a
+# general taxonomy. `--vibes` replaces the lot with a JSON file of the same
+# shape, so a new one does not need a new release.
+#
+# `years` filters on the album's release date, which is what separates eighties
+# synth records from everything a synthpop tag would otherwise drag in.
+DEFAULT_VIBES = (
+    {
+        "name": "80s-synths",
+        "tags": [
+            "synthpop", "synth pop", "synth-pop", "new wave", "synthwave",
+            "new romantic", "electropop", "80s", "1980s",
+        ],
+        "years": [1975, 1992],
+    },
+    {
+        "name": "high-energy-rock",
+        "tags": [
+            "hard rock", "punk rock", "pop punk", "punk", "alternative rock",
+            "rock", "garage rock", "skate punk",
+        ],
+    },
+    {
+        "name": "screamo",
+        "tags": [
+            "screamo", "post-hardcore", "metalcore", "emo", "hardcore",
+            "melodic hardcore", "emocore",
+        ],
+    },
+    {
+        "name": "drum-and-bass",
+        "tags": [
+            "drum and bass", "drum n bass", "dnb", "liquid funk", "neurofunk",
+            "jungle", "breakbeat",
+        ],
+    },
+    {
+        "name": "dance",
+        "tags": [
+            "electro house", "house", "big room", "electronic dance music",
+            "edm", "hardstyle", "trance", "dubstep", "electro",
+        ],
+    },
+    {
+        "name": "classic-rock",
+        "tags": [
+            "classic rock", "progressive rock", "psychedelic rock",
+            "blues rock", "70s", "60s",
+        ],
+    },
+)
+
+
+def load_vibes(path):
+    """Return the vibe definitions, from a file when one is given.
+
+    Validated up front rather than at write time: a bad name would otherwise
+    surface as a file created somewhere unintended, which is a poor way to find
+    out about a typo.
+    """
+    if not path:
+        return DEFAULT_VIBES
+    try:
+        loaded = json.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise ValueError(f"cannot read vibes from {path}: {error}") from error
+
+    if not isinstance(loaded, list):
+        raise ValueError(f"{path}: expected a list of vibes")
+    for vibe in loaded:
+        name = vibe.get("name") if isinstance(vibe, dict) else None
+        if not name or not SAFE_VIBE_NAME.fullmatch(str(name)):
+            raise ValueError(f"{path}: {name!r} is not a usable vibe name (a-z, 0-9, -)")
+        if not vibe.get("tags"):
+            raise ValueError(f"{path}: vibe {name!r} lists no tags")
+    return tuple(loaded)
+
+
+def parse_tags(payload):
+    """Return (tag, weight) pairs from an artist.getTopTags response.
+
+    The documented sample carries only a name and a URL per tag; a live response
+    also carries a 0-100 `count`. Rather than depend on which, the count is used
+    when present and the documented ordering -- by popularity -- stands in for it
+    when it is not.
+    """
+    block = payload.get("toptags") or {}
+    pairs = []
+    for position, entry in enumerate(as_list(block.get("tag"))):
+        tag = (entry.get("name") or "").strip().casefold()
+        if not tag:
+            continue
+        weight = int(entry.get("count") or 0) or max(1, 100 - position * 5)
+        pairs.append((tag, weight))
+    return pairs
+
+
+def sync_tags(client, store, now, limit=0):
+    """Fetch crowd tags for library artists that have none, or stale ones.
+
+    One request per artist, once, and then only for artists newly added. An
+    artist Last.fm has never heard of is recorded as fetched with no tags, so it
+    is not asked about again every pass.
+    """
+    stale = store.connection.execute(
+        "SELECT a.norm_name AS norm_name, a.name AS name, a.mbid AS mbid"
+        "  FROM lidarr_artist a"
+        "  LEFT JOIN artist_tag_fetched f ON f.norm_artist = a.norm_name"
+        " WHERE a.norm_name <> ''"
+        "   AND (f.fetched_at IS NULL OR f.fetched_at < :cutoff)"
+        " ORDER BY a.name",
+        {"cutoff": now - TAG_REFRESH_SECONDS},
+    ).fetchall()
+    if not stale:
+        return 0
+
+    if limit > 0 and len(stale) > limit:
+        logger.info("tagging %d of %d artists this pass; the rest follow next", limit, len(stale))
+        stale = stale[:limit]
+    else:
+        logger.info("fetching tags for %d artists", len(stale))
+
+    tagged = 0
+    for artist in stale:
+        query = {"mbid": artist["mbid"]} if artist["mbid"] else {"artist": artist["name"]}
+        try:
+            payload = client.call("artist.getTopTags", {**query, "autocorrect": 1})
+        except LastfmError as error:
+            # One artist Last.fm cannot answer for is not worth losing the pass.
+            logger.warning("no tags for %s: %s", artist["name"], error)
+            continue
+        store.replace_tags(artist["norm_name"], parse_tags(payload), now)
+        tagged += 1
+
+    logger.info("tagged %d artists", tagged)
+    return tagged
+
+
+def build_vibe_playlists(store, vibes, mirror_root, library_root, limit, now):
+    """Write one playlist per mood. Returns how many tracks were listed."""
+    if not store.scalar("SELECT COUNT(*) FROM artist_tag"):
+        return 0
+
+    directory = Path(mirror_root) / PLAYLIST_DIRECTORY
+    week = now // ROTATION_PERIOD_SECONDS
+    total = 0
+
+    for vibe in vibes:
+        tags = [str(tag).strip().casefold() for tag in vibe["tags"]]
+        placeholders = ",".join("?" * len(tags))
+        years = vibe.get("years")
+        parameters = [*tags, vibe.get("min_score", VIBE_MIN_SCORE)]
+        year_clause = ""
+        if years:
+            year_clause = (
+                " AND CAST(substr(al.release_date, 1, 4) AS INTEGER) BETWEEN ? AND ?"
+            )
+            parameters += [int(years[0]), int(years[1])]
+        parameters += [week, limit]
+
+        sql = f"""
+            WITH vibe AS (
+                SELECT norm_artist, SUM(weight) AS score
+                  FROM artist_tag
+                 WHERE tag IN ({placeholders})
+                 GROUP BY norm_artist
+                HAVING SUM(weight) >= ?
+            )
+            SELECT t.id AS id, a.name AS artist, t.title AS title,
+                   t.duration AS duration, t.path AS path
+              FROM lidarr_track t
+              JOIN lidarr_artist a ON a.id = t.artist_id
+              JOIN vibe v ON v.norm_artist = a.norm_name
+              LEFT JOIN lidarr_album al ON al.id = t.album_id
+             WHERE {PLAYABLE}{year_clause}
+             ORDER BY ((t.id * {SHUFFLE_MULTIPLIER}) + ?) % {SHUFFLE_MODULUS}
+             LIMIT ?
+        """
+
+        entries = []
+        for row in store.connection.execute(sql, parameters):
+            mirror = mirror_path_for(row["path"], library_root, mirror_root)
+            if mirror is None or not mirror.is_file():
+                continue
+            entries.append({**dict(row), "mirror": mirror})
+
+        write_playlist(directory / f"{vibe['name']}.m3u", entries)
+        total += len(entries)
+        logger.info("playlist %-20s %4d tracks -- by tag", vibe["name"], len(entries))
+
+    return total
+
+
 def library_root_of(store):
     """Return the directory Lidarr's artist folders sit under.
 
@@ -1494,7 +1736,7 @@ def report(store, now):
 
 def run_once(
     client, store, user, now, backfill_limit, lidarr=None, mirror=None,
-    library_root=None, playlist_limit=100,
+    library_root=None, playlist_limit=100, vibes=DEFAULT_VIBES, tag_limit=0,
 ):
     """Run a single pass. Returns the number of scrobbles added."""
     started = time.monotonic()
@@ -1517,6 +1759,8 @@ def run_once(
                 )
             else:
                 build_playlists(store, mirror, root, playlist_limit, now)
+                sync_tags(client, store, now, limit=tag_limit)
+                build_vibe_playlists(store, vibes, mirror, root, playlist_limit, now)
 
     logger.info(
         "pass complete in %.1fs: %d scrobbles added, %d loved",
@@ -1608,6 +1852,18 @@ def build_parser():
         default=int(os.getenv("MUSIC_CURATOR_PLAYLIST_LIMIT", "100")),
         help="most tracks to put in any one playlist (env MUSIC_CURATOR_PLAYLIST_LIMIT)",
     )
+    parser.add_argument(
+        "--vibes",
+        default=os.getenv("MUSIC_CURATOR_VIBES"),
+        help="JSON file of mood definitions, replacing the built-in set"
+        " (env MUSIC_CURATOR_VIBES)",
+    )
+    parser.add_argument(
+        "--tag-limit",
+        type=int,
+        default=int(os.getenv("MUSIC_CURATOR_TAG_LIMIT", "0")),
+        help="cap artist tag lookups per pass; 0 for no cap (env MUSIC_CURATOR_TAG_LIMIT)",
+    )
     parser.add_argument(
         "--skip-index",
         action="store_true",
@@ -1632,6 +1888,7 @@ def main(argv=None, clock=time.time):
 
     try:
         interval = parse_interval(args.interval) if args.interval else None
+        vibes = load_vibes(args.vibes)
     except ValueError as error:
         logger.error("%s", error)
         return 2
@@ -1682,6 +1939,8 @@ def main(argv=None, clock=time.time):
                     args.mirror,
                     args.library_root,
                     args.playlist_limit,
+                    vibes,
+                    args.tag_limit,
                 )
             except (LastfmError, LidarrError) as error:
                 logger.error("%s", error)