wip on autotagging
This commit is contained in:
+48
-117
@@ -1,130 +1,61 @@
|
||||
# Roadmap: YellowJacket
|
||||
# YellowJacket — Roadmap
|
||||
|
||||
**Created:** 2026-02-27
|
||||
**Last updated:** 2026-03-18
|
||||
A cross-platform desktop music player. Plays local MP3 / FLAC / OGG / WAV; manages multiple library directories via SQLite; queue, playlists, smart playlists, play history, full-text search, cover art, MPRIS controls on Linux, full single + batch tag editing across all four formats, and a read-only MusicBrainz / ListenBrainz catalog browser.
|
||||
|
||||
## Milestones
|
||||
The guiding rule for everything below is "the music player works reliably and feels solid" — every interaction should be correct, responsive, and trustworthy. New surface area only goes in once the foundation under it is stable.
|
||||
|
||||
- ✅ **v1.0 Consolidation** — Phases 1-8 (shipped 2026-03-05) — [archive](milestones/v1.0-ROADMAP.md)
|
||||
- ✅ **v1.1 Multi-Library Support** — Phases 9-14 (shipped 2026-03-16) — [archive](milestones/v1.1-ROADMAP.md)
|
||||
- ✅ **v1.2 Tag Editing** — Phases 15-18 (shipped 2026-03-18) — [archive](milestones/v1.2-ROADMAP.md)
|
||||
- 🔄 **v1.2.1 Format Parity** — Phases 19-21 (in progress)
|
||||
## Capability set
|
||||
|
||||
## Phases
|
||||
- **Playback** — play / pause / seek / volume on MP3, FLAC, OGG, WAV. Queue with shuffle (Fisher-Yates), repeat (off / one / all), auto-advance, persistent across restarts.
|
||||
- **Library** — multiple library directories, concurrent metadata extraction, adaptive scan concurrency by disk type, cancellable / pausable scans, cross-library playlists with phantom-track preservation when a library is removed.
|
||||
- **Search & browse** — FTS5 across tracks/artists/albums/paths; browse by albums / artists / genres; library filter respected everywhere; virtual scrolling.
|
||||
- **Playlists** — CRUD, M3U8 import/export, favorites, smart playlists (rule-based saved queries with combobox editor + live preview), default playlist.
|
||||
- **Tag editing** — single + batch edit of 8 fields across all four formats; cover art embed/replace/remove; crash-safe atomic writes; instant DB + FTS5 sync, no rescan needed.
|
||||
- **Play history** — natural-finish play counting, `last_played` timestamp, play-history log, integration into smart playlist rule fields.
|
||||
- **Explore** — read-only MusicBrainz / ListenBrainz browser: search → artist page → album detail with release-version selection, with rate-limited APIs and SQLite-cached responses.
|
||||
- **Configuration & system** — TOML config with live reload, configurable keyboard shortcuts (record-style capture, scope-aware dispatch), theme tokens (accent / background shade), MPRIS2 on Linux.
|
||||
|
||||
<details>
|
||||
<summary>✅ v1.0 Consolidation (Phases 1-8) — SHIPPED 2026-03-05</summary>
|
||||
## Milestone sequence
|
||||
|
||||
- [x] Phase 1: Concurrency Race Fixes (1/1 plans) — completed 2026-02-28
|
||||
- [x] Phase 2: Backend Correctness (2/2 plans) — completed 2026-03-03
|
||||
- [x] Phase 3: Test Infrastructure (1/1 plans) — completed 2026-03-04
|
||||
- [x] Phase 4: Queue, Config & Player Tests (2/2 plans) — completed 2026-03-04
|
||||
- [x] Phase 5: Database & Library Tests (2/2 plans) — completed 2026-03-04
|
||||
- [x] Phase 6: SQL Consolidation & Code Quality (3/3 plans) — completed 2026-03-04
|
||||
- [x] Phase 7: Backend Performance (2/2 plans) — completed 2026-03-05
|
||||
- [x] Phase 8: Frontend Performance & UX (4/4 plans) — completed 2026-03-05
|
||||
| # | Milestone | Status | File |
|
||||
|---|-----------|--------|------|
|
||||
| 001 | v1.0 Consolidation | shipped 2026-03-05 | [completed/001-v1.0-consolidation.md](plans/completed/001-v1.0-consolidation.md) |
|
||||
| 002 | v1.1 Multi-Library Support | shipped 2026-03-16 | [completed/002-v1.1-multi-library.md](plans/completed/002-v1.1-multi-library.md) |
|
||||
| 003 | v1.2 Tag Editing (MP3 + FLAC) | shipped 2026-03-18 | [completed/003-v1.2-tag-editing.md](plans/completed/003-v1.2-tag-editing.md) |
|
||||
| 004 | v1.2.1 Format Parity (OGG + WAV) | shipped 2026-03-21 | [completed/004-v1.2.1-format-parity.md](plans/completed/004-v1.2.1-format-parity.md) |
|
||||
| 005 | Smart Playlists | shipped 2026-03-22 | [completed/005-smart-playlists.md](plans/completed/005-smart-playlists.md) |
|
||||
| 006 | Play History & Play Count | shipped 2026-03-22 | [completed/006-play-history.md](plans/completed/006-play-history.md) |
|
||||
| 007 | MusicBrainz/ListenBrainz Explore Browser | shipped 2026-03-24 | [completed/007-explore-browser.md](plans/completed/007-explore-browser.md) |
|
||||
| 008 | Autotag — Schema & Grouping Foundation | shipped 2026-04-20 | [completed/008-autotag-schema-grouping.md](plans/completed/008-autotag-schema-grouping.md) |
|
||||
| 009 | Autotag — Scoring Engine & MB Orchestration | shipped 2026-04-21 | [completed/009-autotag-scoring-engine.md](plans/completed/009-autotag-scoring-engine.md) |
|
||||
| 010 | Autotag — Review UI & Apply Pipeline | **active** | [active/010-autotag-review-ui.md](plans/active/010-autotag-review-ui.md) |
|
||||
| 011 | Autotag — Auto-Accept & Entry Points | pending | [pending/011-autotag-auto-accept.md](plans/pending/011-autotag-auto-accept.md) |
|
||||
| 012 | Autotag — Settings & Polish | pending | [pending/012-autotag-settings-polish.md](plans/pending/012-autotag-settings-polish.md) |
|
||||
|
||||
</details>
|
||||
The active phase is the **MusicBrainz autotagger** (collectively v1.3). It builds on the explore-browser API client + cache foundation from milestone 007. Plans 008-012 are sequential — each depends on the prior one. See `NOTES.md` for the API-call-minimization playbook and the design principles that constrain every Autotag plan.
|
||||
|
||||
<details>
|
||||
<summary>✅ v1.1 Multi-Library Support (Phases 9-14) — SHIPPED 2026-03-16</summary>
|
||||
## Beyond v1.3 (not yet planned)
|
||||
|
||||
- [x] Phase 9: Scan Cancellation & Keyboard Shortcuts (5/5 plans) — completed 2026-03-07
|
||||
- [x] Phase 10: Schema & Migration (2/2 plans) — completed 2026-03-09
|
||||
- [x] Phase 11: Per-Library Scan Pipeline (3/3 plans) — completed 2026-03-09
|
||||
- [x] Phase 12: Library CRUD & Data Integrity (2/2 plans) — completed 2026-03-15
|
||||
- [x] Phase 13: Library Views & Phantom Tracks (2/2 plans) — completed 2026-03-16
|
||||
- [x] Phase 14: Performance Optimization (4/4 plans) — completed 2026-03-15
|
||||
Captured here so they don't get lost; not yet promoted to plan files.
|
||||
|
||||
</details>
|
||||
- **ListenBrainz scrobbling.** Submit play data when a track crosses the scrobble threshold (`min(duration / 2, 4 minutes)`). Three submission types — `playing_now`, `single`, `import`. Hook slots in next to the existing play-history pipeline; MBIDs already flow through the stack thanks to v1.3.
|
||||
- **Gapless playback + crossfade.** Seamless transitions with optional crossfade.
|
||||
- **Layout customization system.** Section-based UI customization; components declare size constraints, users configure per-section.
|
||||
- **Plugin system.** Full-access API for UI components and backend hooks.
|
||||
- **AcoustID fingerprinting** via fpcalc — slots in behind the v1.3 `Identifier` interface seam.
|
||||
|
||||
<details>
|
||||
<summary>✅ v1.2 Tag Editing (Phases 15-18) — SHIPPED 2026-03-18</summary>
|
||||
## Out of scope
|
||||
|
||||
- [x] Phase 15: Schema Migration & Write Safety (2/2 plans) — completed 2026-03-16
|
||||
- [x] Phase 16: Tag Writing & Database Sync (3/3 plans) — completed 2026-03-17
|
||||
- [x] Phase 17: Single Track Edit (2/2 plans) — completed 2026-03-18
|
||||
- [x] Phase 18: Batch Edit (2/2 plans) — completed 2026-03-18
|
||||
Things deliberately **not** going in. See `NOTES.md` for the reasoning behind each.
|
||||
|
||||
**Deferred:** Phase 19 (OGG Vorbis Tag Writing) — stretch goal, deferred to v1.2.1
|
||||
|
||||
</details>
|
||||
|
||||
### v1.2.1 Format Parity (Phases 19-21)
|
||||
|
||||
- [x] **Phase 19: WAV Tag Writer** — Full metadata and cover art writing for WAV files via ID3v2-in-RIFF (completed 2026-03-19)
|
||||
- [x] **Phase 20: OGG Vorbis Tag Writer** — Full metadata and cover art writing for OGG Vorbis files via custom page rewriter (completed 2026-03-19)
|
||||
- [ ] **Phase 21: Cleanup** — Fix lint warnings and small issues carried forward from v1.2
|
||||
|
||||
## Phase Details
|
||||
|
||||
### Phase 19: WAV Tag Writer
|
||||
**Goal**: Users can edit metadata and cover art on WAV files with the same experience as MP3/FLAC
|
||||
**Depends on**: Nothing (extends existing tag writing pipeline)
|
||||
**Requirements**: WAV-01, WAV-02, WAV-03, WAV-04, WAV-05, WAV-06
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. User can open a WAV file in the single-track editor, change any of the 8 text fields, save, and see the changes persist after re-scanning the library
|
||||
2. User can embed, replace, or remove cover art on a WAV file and see the updated artwork in the track list and player
|
||||
3. Editing a WAV file's tags does not alter audio playback — the file sounds identical before and after
|
||||
4. Existing metadata in the WAV file that wasn't edited (RIFF INFO chunks, bext, cue markers) survives the tag write unchanged
|
||||
5. If the app crashes or loses power during a WAV tag write, the original file is intact (not corrupted or truncated)
|
||||
**Plans:** 2/2 plans complete
|
||||
|
||||
Plans:
|
||||
- [ ] 19-01-PLAN.md — WAV RIFF parser/writer and writeWavTags function
|
||||
- [ ] 19-02-PLAN.md — WAV tag writer round-trip tests
|
||||
|
||||
### Phase 20: OGG Vorbis Tag Writer
|
||||
**Goal**: Users can edit metadata and cover art on OGG Vorbis files with the same experience as MP3/FLAC/WAV
|
||||
**Depends on**: Phase 19 (pipeline extension pattern proven)
|
||||
**Requirements**: OGG-01, OGG-02, OGG-03, OGG-04, OGG-05, OGG-06
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. User can open an OGG Vorbis file in the single-track editor, change any of the 8 text fields, save, and see the changes persist after re-scanning the library
|
||||
2. User can embed, replace, or remove cover art on an OGG Vorbis file via METADATA_BLOCK_PICTURE and see the updated artwork in the track list and player
|
||||
3. Editing an OGG file's tags does not alter audio playback — the file sounds identical before and after
|
||||
4. Existing Vorbis Comments that weren't edited (ReplayGain, lyrics, custom fields) survive the tag write unchanged
|
||||
5. If the app crashes or loses power during an OGG tag write, the original file is intact (not corrupted or truncated)
|
||||
**Plans:** 2/2 plans complete
|
||||
|
||||
Plans:
|
||||
- [ ] 20-01-PLAN.md — OGG page parser/writer, Vorbis Comment serializer, writeOggTags, pipeline integration
|
||||
- [ ] 20-02-PLAN.md — OGG tag writer round-trip tests
|
||||
|
||||
### Phase 21: Cleanup
|
||||
**Goal**: Codebase is clean — no lint warnings or loose ends from tag editing work
|
||||
**Depends on**: Phase 20 (cleanup after all format work is done)
|
||||
**Requirements**: CLEAN-01, CLEAN-02
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. `make lint` passes with zero warnings in dbsync.go and tagwriter.go (nlreturn/wsl violations resolved)
|
||||
2. Any small issues discovered during v1.2 tag editing milestone are resolved
|
||||
**Plans**: TBD
|
||||
|
||||
## Progress
|
||||
|
||||
| Phase | Milestone | Plans Complete | Status | Completed |
|
||||
|-------|-----------|----------------|--------|-----------|
|
||||
| 1. Concurrency Race Fixes | v1.0 | 1/1 | Complete | 2026-02-28 |
|
||||
| 2. Backend Correctness | v1.0 | 2/2 | Complete | 2026-03-03 |
|
||||
| 3. Test Infrastructure | v1.0 | 1/1 | Complete | 2026-03-04 |
|
||||
| 4. Queue, Config & Player Tests | v1.0 | 2/2 | Complete | 2026-03-04 |
|
||||
| 5. Database & Library Tests | v1.0 | 2/2 | Complete | 2026-03-04 |
|
||||
| 6. SQL Consolidation & Code Quality | v1.0 | 3/3 | Complete | 2026-03-04 |
|
||||
| 7. Backend Performance | v1.0 | 2/2 | Complete | 2026-03-05 |
|
||||
| 8. Frontend Performance & UX | v1.0 | 4/4 | Complete | 2026-03-05 |
|
||||
| 9. Scan Cancellation & Keyboard Shortcuts | v1.1 | 5/5 | Complete | 2026-03-07 |
|
||||
| 10. Schema & Migration | v1.1 | 2/2 | Complete | 2026-03-09 |
|
||||
| 11. Per-Library Scan Pipeline | v1.1 | 3/3 | Complete | 2026-03-09 |
|
||||
| 12. Library CRUD & Data Integrity | v1.1 | 2/2 | Complete | 2026-03-15 |
|
||||
| 13. Library Views & Phantom Tracks | v1.1 | 2/2 | Complete | 2026-03-16 |
|
||||
| 14. Performance Optimization | v1.1 | 4/4 | Complete | 2026-03-15 |
|
||||
| 15. Schema Migration & Write Safety | v1.2 | 2/2 | Complete | 2026-03-16 |
|
||||
| 16. Tag Writing & Database Sync | v1.2 | 3/3 | Complete | 2026-03-17 |
|
||||
| 17. Single Track Edit | v1.2 | 2/2 | Complete | 2026-03-18 |
|
||||
| 18. Batch Edit | v1.2 | 2/2 | Complete | 2026-03-18 |
|
||||
| 19. WAV Tag Writer | 2/2 | Complete | 2026-03-19 | - |
|
||||
| 20. OGG Vorbis Tag Writer | 2/2 | Complete | 2026-03-19 | - |
|
||||
| 21. Cleanup | v1.2.1 | 0/? | Not started | - |
|
||||
|
||||
---
|
||||
*Roadmap created: 2026-02-27*
|
||||
*Last updated: 2026-03-18 — v1.2.1 Format Parity roadmap created*
|
||||
- Separate databases per library, auto-dedup across libraries, user access control per library.
|
||||
- Parallel library scanning (SQLite single-writer).
|
||||
- Cross-platform media controls beyond MPRIS on Linux.
|
||||
- Database health checking / reconnection.
|
||||
- ORM or query builder, connection pooling for SQLite.
|
||||
- Parenthesized boolean logic in smart playlists; "is favorited" as a filter; queue that re-evaluates rules during playback.
|
||||
- Playing audio from MusicBrainz remotely (it's a metadata catalog, not a streaming service).
|
||||
- Integrating any service beyond MusicBrainz / ListenBrainz / Cover Art Archive without explicit user approval.
|
||||
- Fuzzy auto-accept threshold sliders (strict all-match is the trustworthy default).
|
||||
- Manual MB search UI (Paste-URL covers the escape-hatch case).
|
||||
- Cover art replacement during auto-accept (highest-regret op — never automatic in v1).
|
||||
|
||||
Reference in New Issue
Block a user