yonlu/yellowjacket
1
1
Fork 0
Code Issues 52 Pull Requests 4 Actions Packages Projects Releases 12 Wiki Activity
Files
cb5155b8906357ff77c5c579d57d02cf2eec6abe
yellowjacket/.planning/ROADMAP.md
T

9.5 KiB
Raw Blame History

Roadmap: YellowJacket

Created: 2026-02-27 Last updated: 2026-03-16 Current milestone: v1.2 Tag Editing

Milestones

  • ✅ v1.0 Consolidation — Phases 1-8 (shipped 2026-03-05) — archive
  • ✅ v1.1 Multi-Library Support — Phases 9-14 (shipped 2026-03-16) — archive
  • 🔨 v1.2 Tag Editing — Phases 15-19

Phases

✅ v1.0 Consolidation (Phases 1-8) — SHIPPED 2026-03-05
  • Phase 1: Concurrency Race Fixes (1/1 plans) — completed 2026-02-28
  • Phase 2: Backend Correctness (2/2 plans) — completed 2026-03-03
  • Phase 3: Test Infrastructure (1/1 plans) — completed 2026-03-04
  • Phase 4: Queue, Config & Player Tests (2/2 plans) — completed 2026-03-04
  • Phase 5: Database & Library Tests (2/2 plans) — completed 2026-03-04
  • Phase 6: SQL Consolidation & Code Quality (3/3 plans) — completed 2026-03-04
  • Phase 7: Backend Performance (2/2 plans) — completed 2026-03-05
  • Phase 8: Frontend Performance & UX (4/4 plans) — completed 2026-03-05
✅ v1.1 Multi-Library Support (Phases 9-14) — SHIPPED 2026-03-16
  • Phase 9: Scan Cancellation & Keyboard Shortcuts (5/5 plans) — completed 2026-03-07
  • Phase 10: Schema & Migration (2/2 plans) — completed 2026-03-09
  • Phase 11: Per-Library Scan Pipeline (3/3 plans) — completed 2026-03-09
  • Phase 12: Library CRUD & Data Integrity (2/2 plans) — completed 2026-03-15
  • Phase 13: Library Views & Phantom Tracks (2/2 plans) — completed 2026-03-16
  • Phase 14: Performance Optimization (4/4 plans) — completed 2026-03-15

v1.2 Tag Editing (Phases 15-19)

  • Phase 15: Schema Migration & Write Safety — FTS5 contentless_delete migration and atomic file write utility
  • Phase 16: Tag Writing & Database Sync — Format-specific tag writers (MP3, FLAC, cover art) with inline DB + FTS5 update pipeline
  • Phase 17: Single Track Edit — End-to-end single track editing: UI → file write → DB sync → view refresh
  • Phase 18: Batch Edit — Multi-select batch editing with three-state field model, progress, and batch cover art
  • Phase 19: OGG Vorbis Tag Writing — Custom OGG page rewriter for Vorbis Comment tag writing (stretch)

Phase Details

Phase 15: Schema Migration & Write Safety

Goal: The database and file system infrastructure supports safe, reversible tag editing — FTS5 rows can be deleted/updated and file writes never corrupt audio files Depends on: Nothing (builds on v1.1 foundation) Requirements: SCHEMA-01, SCHEMA-02, WRITE-05 Success Criteria (what must be TRUE):

  1. FTS5 search_index uses contentless_delete=1 — deleting or updating a track's metadata in the DB correctly removes the old FTS5 entry without stale ghost results appearing in search
  2. Existing search functionality is unaffected — all current queries, ranking, and library-filtered search continue to work identically after migration
  3. The atomic write utility writes to a temp file in the same directory as the target, then renames — if the process crashes mid-write, the original file is intact and the temp file is cleaned up on next startup
  4. Unit tests verify atomic write behavior: successful write, crash simulation (temp file left behind), and cross-directory rejection Plans: TBD

Phase 16: Tag Writing & Database Sync

Goal: The backend can write metadata tags and cover art to MP3 and FLAC files, then synchronize all changes to the database and search index in a single atomic operation Depends on: Phase 15 (requires atomic write utility and FTS5 contentless_delete) Requirements: WRITE-01, WRITE-02, WRITE-04, WRITE-06, SYNC-01, SYNC-02, SYNC-03, SYNC-04 Success Criteria (what must be TRUE):

  1. A Go function can accept a track ID and a set of changed metadata fields, write those tags to an MP3 file (ID3v2), and the tags are readable back by the existing metadata reader — round-trip correctness verified by unit tests with real audio files
  2. The same function works for FLAC files (Vorbis Comments) — including files with existing padding blocks and multiple metadata blocks
  3. Cover art images (JPEG/PNG) can be embedded in both MP3 and FLAC files — the embedded image is readable back and the existing cover art pipeline (extraction, thumbnails) works with the newly embedded art
  4. After a tag write, the database reflects the new metadata within the same operation: artist/album/genre entities are created or relinked (never mutated in-place), orphaned entities with zero remaining references are cleaned up, and the FTS5 index is updated — no library rescan needed
  5. If the currently-playing track is being edited, playback is stopped before the file write begins — the user does not experience a crash or corrupted audio stream Plans: TBD

Phase 17: Single Track Edit

Goal: Users can edit any track's metadata and cover art from within the app and see changes reflected everywhere immediately Depends on: Phase 16 (requires tag writers and DB sync pipeline) Requirements: EDIT-01, EDIT-02, EDIT-03, EDIT-04 Success Criteria (what must be TRUE):

  1. User can right-click any track (in track list, album detail, queue, or playlist) and open a tag editor dialog — the editor is accessible from every place tracks appear
  2. The editor displays all 8 editable fields (title, artist, album, genre, year, track number, disc number, composer) pre-populated with the track's current values — empty fields show as empty, not "Unknown"
  3. The editor displays the track's current cover art (or a placeholder if none) with a button to select a replacement image file from disk
  4. Clicking "Save" writes the changes to the audio file, updates the database and search index, and refreshes all visible views (track list, album view, artist view, genre view, queue, now-playing bar) — the user sees the new metadata everywhere without restarting or rescanning Plans: TBD

Phase 18: Batch Edit

Goal: Users can efficiently edit shared metadata across multiple tracks at once with clear visual feedback and safe defaults Depends on: Phase 17 (requires single-track edit pipeline as foundation) Requirements: BATCH-01, BATCH-02, BATCH-03, BATCH-04 Success Criteria (what must be TRUE):

  1. User can select multiple tracks (via multi-select in track list or album detail) and open a batch editor — the batch editor is accessible from the same context menu as single-track edit
  2. Each field in the batch editor shows one of three states: "keep original" (mixed values, no change), "set to value" (apply this value to all selected tracks), or "clear field" (remove this value from all) — the user can see which fields differ across the selection and choose per-field what to do
  3. For batch operations on 10+ tracks, a progress indicator shows how many tracks have been processed — the user is never left staring at a frozen UI wondering if the operation is working
  4. User can set cover art for all selected tracks at once — the same image is embedded in every selected file Plans: TBD

Phase 19: OGG Vorbis Tag Writing

Goal: Users can edit tags on OGG Vorbis files with the same experience as MP3 and FLAC — completing full format coverage Depends on: Phase 16 (requires tag writer interface and DB sync pipeline) Requirements: WRITE-03 Success Criteria (what must be TRUE):

  1. A Go function can write Vorbis Comment metadata tags to OGG Vorbis files using a custom OGG page rewriter — the file remains a valid OGG stream after writing (playable by the existing player and by external players)
  2. Tag writes to OGG files use the same atomic write-to-temp-then-rename pattern as MP3/FLAC — no corruption risk
  3. OGG tag editing is seamlessly integrated into the single-track and batch edit UIs — the user doesn't need to know or care what format a file is; the editor just works 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 0/? Not started -
16. Tag Writing & Database Sync v1.2 0/? Not started -
17. Single Track Edit v1.2 0/? Not started -
18. Batch Edit v1.2 0/? Not started -
19. OGG Vorbis Tag Writing v1.2 0/? Not started -

Roadmap created: 2026-02-27 Last updated: 2026-03-16 — v1.2 Tag Editing milestone roadmap created (Phases 15-19)

Reference in New Issue View Git Blame Copy Permalink