# Requirements: YellowJacket

**Defined:** 2026-03-16
**Core Value:** The music player works reliably and feels solid — every interaction is correct, responsive, and trustworthy.

## v1.2 Requirements

Requirements for v1.2 Tag Editing milestone. Each maps to roadmap phases.

### Schema & Safety

- [ ] **SCHEMA-01**: FTS5 search_index migrated to `contentless_delete=1` for safe row-level updates
- [ ] **SCHEMA-02**: Atomic file write utility (write-to-temp-then-rename in same directory)

### Tag Writing

- [ ] **WRITE-01**: Write metadata tags to MP3 files via ID3v2 (title, artist, album, genre, year, track#, disc#, composer)
- [ ] **WRITE-02**: Write metadata tags to FLAC files via Vorbis Comments
- [ ] **WRITE-03**: Write metadata tags to OGG Vorbis files via custom page rewriter
- [ ] **WRITE-04**: Embed cover art image (JPEG/PNG) in MP3 and FLAC files
- [ ] **WRITE-05**: All file writes use atomic write-to-temp-then-rename to prevent corruption
- [ ] **WRITE-06**: Currently-playing file is stopped before writing (player safety)

### Database Sync

- [ ] **SYNC-01**: After tag write, update DB entities inline (upsert-and-relink for artist, album, genre)
- [ ] **SYNC-02**: After tag write, update FTS5 search index for affected tracks
- [ ] **SYNC-03**: Orphaned entities (artists, albums, genres no longer referenced) cleaned up
- [ ] **SYNC-04**: Scan pipeline paused during tag writes to prevent race conditions

### Single Track Edit

- [ ] **EDIT-01**: User can open tag editor for a single track from context menu or detail view
- [ ] **EDIT-02**: Editor shows all 8 editable fields with current values pre-populated
- [ ] **EDIT-03**: Editor shows current cover art with option to replace from image file
- [ ] **EDIT-04**: Saving writes tags to file, updates DB, updates FTS5, and refreshes all views immediately

### Batch Edit

- [ ] **BATCH-01**: User can select multiple tracks and open batch editor
- [ ] **BATCH-02**: Batch editor uses three-state field model (keep original / set value / clear field)
- [ ] **BATCH-03**: Batch editor shows progress indicator for large selections
- [ ] **BATCH-04**: User can set cover art for all selected tracks at once

## Future Requirements

Deferred to future milestones. Tracked but not in current roadmap.

### Tag Editing (v2+)

- **EDIT-F01**: Undo/redo for tag edits
- **EDIT-F02**: Auto-capitalize and clean tag values
- **EDIT-F03**: Filename-to-tag inference (parse "Artist - Title.mp3" patterns)
- **EDIT-F04**: Tag-to-filename rename based on template
- **EDIT-F05**: WAV tag writing

### Smart Playlists (Deferred from v1.1)

- **SMRT-01**: User can create a smart playlist with filter rules (genre, year, artist, album, title)
- **SMRT-02**: Multiple rules combine with AND logic
- **SMRT-03**: User can set random ordering and result limit ("Random 50 Jazz tracks")

### Gapless Playback (Deferred from v1.1)

- **GAP-01**: Tracks transition seamlessly with no audible silence gap (gapless playback)
- **GAP-02**: Next track is pre-decoded before current track ends
- **GAP-03**: User can enable/disable crossfade with configurable duration

### Other Deferred

- **MB-01**: MusicBrainz artist/discography browser
- **LAYOUT-01**: Layout customization system (section-based UI)
- **PLUG-01**: Plugin system (extensibility foundation)

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| OGG Vorbis tag writing (if infeasible) | No pure-Go library exists; custom OGG page rewriter may prove too complex — treat as stretch goal |
| WAV metadata editing | Rarely needed, low priority |
| Auto-tag from MusicBrainz | Complex matching logic — Picard's domain |
| Batch rename files from tags | High risk of data loss; defer to v2+ with undo support |
| Lossless audio re-encoding | Not a tag editor concern |
| Parallel library scanning | SQLite single-writer constraint |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| SCHEMA-01 | Phase 15 | Pending |
| SCHEMA-02 | Phase 15 | Pending |
| WRITE-01 | Phase 16 | Pending |
| WRITE-02 | Phase 16 | Pending |
| WRITE-03 | Phase 19 | Pending |
| WRITE-04 | Phase 16 | Pending |
| WRITE-05 | Phase 15 | Pending |
| WRITE-06 | Phase 16 | Pending |
| SYNC-01 | Phase 16 | Pending |
| SYNC-02 | Phase 16 | Pending |
| SYNC-03 | Phase 16 | Pending |
| SYNC-04 | Phase 16 | Pending |
| EDIT-01 | Phase 17 | Pending |
| EDIT-02 | Phase 17 | Pending |
| EDIT-03 | Phase 17 | Pending |
| EDIT-04 | Phase 17 | Pending |
| BATCH-01 | Phase 18 | Pending |
| BATCH-02 | Phase 18 | Pending |
| BATCH-03 | Phase 18 | Pending |
| BATCH-04 | Phase 18 | Pending |

**Coverage:**
- v1.2 requirements: 20 total
- Mapped to phases: 20
- Unmapped: 0 ✓

---
*Requirements defined: 2026-03-16*
*Last updated: 2026-03-16 — traceability updated with phase mappings (Phases 15-19)*