[RFC/Discussion] Library & metadata roadmap from the FeedBack library charrette (difficulty rating, genre/tags, enrichment, DB/ops)

[ChrisBeWithYou]

A multi-disciplinary library design charrette (marketing, UX, dev-ops, gamification, learning-design, ecosystem/borrow-vs-build lenses) studied FeedBack's library + metadata management against homelab "librarianship" apps — the *arr suite (Radarr/Sonarr/Lidarr/Prowlarr), Plex, Jellyfin, Navidrome, Audiobookshelf, Komga/Kavita, Calibre-Web, beets. This issue logs the findings that touch the file format / metadata schema for team review/discussion, plus a cross-referenced summary of the core/app findings.

Two low-risk slices already shipped as core PRs (not spec changes): an A–Z jump rail on the v3 grid (got-feedback/feedback#634) and a practice-aware "Keep practicing" shelf + Repertoire meter (#635). This issue is about the bigger metadata questions that need agreement before building.

Discussions are disabled on this repo, so this is an issue. Convert/split as the team prefers.

---

1. ★ Per-arrangement difficulty rating (the keystone)

Problem. Difficulty is invisible at the library level. There is no per-song/per-arrangement difficulty a user can sort, filter, or see before committing — the only difficulty signal is the phrase-level ladder (§6.7), which exists only inside phrase-aware packs and only once you're in the chart. The learning-design lens called this the keystone gap: you can't sequence easy→mastery, match difficulty to skill, or drive "what to practice next" without it.

Proposal (for discussion). An OPTIONAL difficulty integer (say 1–10) on each arrangements[] entry (§5.2) — per-arrangement so a song's bass vs lead vs rhythm keep distinct ratings (cross-instrument parity). Additive MINOR key per §4.2, so older Readers ignore it.

• Open Qs: scale + meaning (absolute 1–10? a coarse beginner/intermediate/advanced enum?); authored vs derived (a Writer could compute it from note density + tempo (§6.10) + the phrase ladder span (§6.7) + tuning distance) vs both with an authored override; relationship to the existing phrase max_difficulty.
• Why spec, not just app: difficulty should travel with the pack so every host/importer agrees and it survives re-scan — it's metadata about the chart, not the user.

2. Genre + technique/skill tags

Problem. §5.1 carries title/artist/album/year… but no genre, no tags, no bpm at the manifest level. A practice curriculum is organized by the skill a piece builds ("16th-funk-pocket", "alternate-picking", "drop-D"), and a library is browsed by genre. Today neither is expressible or filterable.

Proposal (for discussion). Additive MINOR keys on the top-level manifest (§5.1):

• genre (string or string[]).
• tags (string[]) — free-form, queryable technique/skill/mood tags (the beets "flexible attributes" pattern).
  Older Readers ignore both. The core app would index them → new sort/filter facets.
• Open Qs: controlled vocabulary vs free-form for tags; whether bpm belongs here too (note per-arrangement tempo already lives at §6.10).

3. Metadata enrichment / scraping — OPEN QUESTION (no team consensus yet)

Context. Imports today are manifest→XML→foldername; "Edit Metadata" touches 4 fields; messy imports → an ugly, art-poor grid (marketing flagged this as a demo-wow + adoption-friction issue). Homelab precedent: Lidarr+MusicBrainz, beets autotagger, Komf cover/metadata fetch.

Deliberately raised as a discussion, not a proposal — the team isn't aligned on whether to do online metadata lookup at all. If pursued, the homelab-crowd constraints are non-negotiable: opt-in, offline-first, no silent phone-home, and the natural home is a library provider / enrichment source, not core. Spec angle: if enriched metadata is written back, does it land in the feedpak manifest (and how is provenance/override tracked)? Flagging for a decision before anyone builds.

---

4. Related core/app + DB-ops findings (NOT file-format — cross-referenced here for the charrette record; action lives in got-feedback/feedback)

• Smart / dynamic collections (rule = a saved /api/library filter, auto-refreshing): "needs work (<70%)", "not played in 30d", "drop-D". Ecosystem lens: build as a library provider so it reuses the whole Songs UI + filter vocabulary — minimal core code. (Pairs with genre/tags + difficulty above.)
• Back up web_library.db in the Settings export bundle (dev-ops lens's Add feedpak format specification v1.0.0 #1): scores/favorites/playlists are the only library state a rescan can't rebuild. Reuses the existing #113 backup machinery.
• Grid scaling: the v3 grid is forward-only paged with no virtualization; the new jump rail "loads through" to a letter. A keyset-seek + virtualized window is the follow-up before libraries hit five figures.
• Persisted wishlist / "wanted" (the *arr Wanted-list analogue): extend the existing find_more ownership-diff + the saved_for_later playlist.
• Already covered — don't reinvent: watch-folder (core scanner), ordered setlists (setlist), browse preview (song_preview), fuzzy local match (the_daily).

---

Recommended sequencing

1. Difficulty rating (§1) — the unlock; agree the scale + derived-vs-authored, then it can ride the pack and light up sort/filter/recommendations.
2. genre/tags (§2) — cheap additive keys; big curriculum + browse payoff.
3. enrichment (§3) — decide whether first.
4. Core/DB items (§4) — independent, tracked in the app repo.

cc maintainers — looking for direction on §1's scale and §3's go/no-go in particular.

[ChrisBeWithYou]

§4 (the core/app + DB-ops findings — library-DB backup, smart-collections-as-a-provider, grid virtualization/keyset, wishlist) is now mirrored as a tracking issue in the app repo where it'll be actioned: got-feedBack/feedBack#636. This spec issue stays focused on the file-format / metadata questions (§1–§3).

[topkoa]

Split the three file-format / metadata questions into their own issues so each tracks its own readiness and decision gate (mirroring how §4 went to got-feedBack/feedBack#636). This issue stays as the umbrella / charrette record.

• §1 difficulty rating → [Spec] Per-arrangement difficulty rating on arrangements[] (1.13.0, additive) #37 ([Spec] additive, 1.12.0 — open Q: scale)
• §2 genre/tags → [Spec] Top-level tags manifest key (1.13.0, additive) — genres shipped in 1.12.0 #38 ([Spec] additive, 1.12.0 — open Q: tags vocab; recommends plural genres/tags per §9.2, and no manifest bpm)
• §3 enrichment → [Decision] Online metadata enrichment — go/no-go before any spec work #39 ([Decision] go/no-go first; no spec work until resolved)

§1 and §2 are independent additive MINOR bumps; §3 is a policy decision and gates on its own. Maintainer asks (§1 scale, §3 go/no-go) carried into #37 and #39.

[topkoa]

Roadmap status (spec 1.12.0 merged, PR #40).

• §2 genre/tags — genres shipped in 1.12.0 (top-level, string[], free-form). tags still open, retargeted to 1.13.0 in [Spec] Top-level tags manifest key (1.13.0, additive) — genres shipped in 1.12.0 #38. 1.12.0 also added album_artist/track/disc (album grouping + ordering).
• §1 difficulty rating — still open, retargeted to 1.13.0 in [Spec] Per-arrangement difficulty rating on arrangements[] (1.13.0, additive) #37.
• §3 online enrichment — still a go/no-go decision in [Decision] Online metadata enrichment — go/no-go before any spec work #39; note its writeback targets genres/album/year now exist.