docs(20-02): complete OGG Vorbis tag writer tests plan
This commit is contained in:
@@ -14,7 +14,7 @@ Requirements for Format Parity milestone. Each maps to roadmap phases.
|
||||
- [x] **OGG-03**: OGG tag writes preserve audio data identically (lossless round-trip)
|
||||
- [x] **OGG-04**: User can embed, replace, and remove cover art in OGG Vorbis files via METADATA_BLOCK_PICTURE
|
||||
- [x] **OGG-05**: OGG tag writing uses crash-safe atomic writes (write-to-temp-then-rename)
|
||||
- [ ] **OGG-06**: OGG writer round-trip tests verify all fields via dhowden/tag read-back
|
||||
- [x] **OGG-06**: OGG writer round-trip tests verify all fields via dhowden/tag read-back
|
||||
|
||||
### WAV Tag Writing
|
||||
|
||||
@@ -76,7 +76,7 @@ Which phases cover which requirements. Updated during roadmap creation.
|
||||
| OGG-03 | Phase 20 | Complete |
|
||||
| OGG-04 | Phase 20 | Complete |
|
||||
| OGG-05 | Phase 20 | Complete |
|
||||
| OGG-06 | Phase 20 | Pending |
|
||||
| OGG-06 | Phase 20 | Complete |
|
||||
| CLEAN-01 | Phase 21 | Pending |
|
||||
| CLEAN-02 | Phase 21 | Pending |
|
||||
|
||||
|
||||
@@ -53,7 +53,7 @@
|
||||
### 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)
|
||||
- [ ] **Phase 20: OGG Vorbis Tag Writer** — Full metadata and cover art writing for OGG Vorbis files via custom page rewriter
|
||||
- [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
|
||||
@@ -84,7 +84,7 @@ Plans:
|
||||
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:** 1/2 plans executed
|
||||
**Plans:** 2/2 plans complete
|
||||
|
||||
Plans:
|
||||
- [ ] 20-01-PLAN.md — OGG page parser/writer, Vorbis Comment serializer, writeOggTags, pipeline integration
|
||||
@@ -122,7 +122,7 @@ Plans:
|
||||
| 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 | 1/2 | In Progress| | - |
|
||||
| 20. OGG Vorbis Tag Writer | 2/2 | Complete | 2026-03-19 | - |
|
||||
| 21. Cleanup | v1.2.1 | 0/? | Not started | - |
|
||||
|
||||
---
|
||||
|
||||
+14
-12
@@ -3,12 +3,12 @@ gsd_state_version: 1.0
|
||||
milestone: v1.0
|
||||
milestone_name: milestone
|
||||
status: in-progress
|
||||
last_updated: "2026-03-19T17:53:47Z"
|
||||
last_updated: "2026-03-19T18:02:38Z"
|
||||
progress:
|
||||
total_phases: 1
|
||||
completed_phases: 1
|
||||
total_plans: 4
|
||||
completed_plans: 3
|
||||
completed_plans: 4
|
||||
---
|
||||
|
||||
# YellowJacket — Project State
|
||||
@@ -18,14 +18,14 @@ progress:
|
||||
See: .planning/PROJECT.md (updated 2026-03-18)
|
||||
|
||||
**Core value:** The music player works reliably and feels solid — every interaction is correct, responsive, and trustworthy.
|
||||
**Current focus:** v1.2.1 Format Parity — Phase 20 in progress (OGG Vorbis tag writer)
|
||||
**Current focus:** v1.2.1 Format Parity — Phase 20 complete (OGG Vorbis tag writer)
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 20 — OGG Vorbis Tag Writer (IN PROGRESS)
|
||||
Plan: 1 of 2 complete
|
||||
Status: Plan 01 complete (implementation) — Plan 02 pending (tests)
|
||||
Last activity: 2026-03-19 — Completed 20-01-PLAN.md (OGG Vorbis tag writer implementation)
|
||||
Phase: 20 — OGG Vorbis Tag Writer (COMPLETE)
|
||||
Plan: 2 of 2 complete
|
||||
Status: Phase complete — all plans executed
|
||||
Last activity: 2026-03-19 — Completed 20-02-PLAN.md (OGG Vorbis tag writer tests)
|
||||
|
||||
```
|
||||
v1.2.1 Format Parity
|
||||
@@ -43,6 +43,7 @@ v1.2.1 Format Parity
|
||||
| 19-01 | WAV tag writer impl | 5 min | 2 | 4 |
|
||||
| 19-02 | WAV tag writer tests | 9 min | 3 | 2 |
|
||||
| 20-01 | OGG Vorbis tag writer impl | 3 min | 1 | 4 |
|
||||
| 20-02 | OGG Vorbis tag writer tests | 5 min | 3 | 1 |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
@@ -67,6 +68,7 @@ All decisions archived in PROJECT.md Key Decisions table and RETROSPECTIVE.md. K
|
||||
- Custom OGG CRC32 with precomputed lookup table (hash/crc32 uses incompatible reflected bit ordering)
|
||||
- Raw byte preservation for Vorbis Comment entries — [][]byte instead of []string for non-UTF-8 safety
|
||||
- METADATA_BLOCK_PICTURE + legacy COVERART/COVERARTMIME stripping on all OGG cover art operations
|
||||
- OGG test fixture built programmatically via createTestOGG using page structures (no embedded binary)
|
||||
|
||||
### Warnings (carry forward)
|
||||
|
||||
@@ -90,9 +92,9 @@ All decisions archived in PROJECT.md Key Decisions table and RETROSPECTIVE.md. K
|
||||
### Last Session
|
||||
|
||||
**Date:** 2026-03-19
|
||||
**What happened:** Executed 20-01-PLAN.md — OGG Vorbis tag writer implementation. Created custom OGG page parser/writer with MSB-first CRC32, Vorbis Comment packet serializer with METADATA_BLOCK_PICTURE cover art, and pipeline integration.
|
||||
**Where we stopped:** Completed 20-01-PLAN.md
|
||||
**Next action:** Execute 20-02-PLAN.md (OGG Vorbis tag writer tests)
|
||||
**What happened:** Executed 20-02-PLAN.md — OGG Vorbis tag writer tests. 9 round-trip test functions covering all 6 OGG requirements with programmatic fixture builder and CRC32 validation.
|
||||
**Where we stopped:** Completed 20-02-PLAN.md — Phase 20 complete
|
||||
**Next action:** Plan/execute next phase (Phase 21 or milestone completion)
|
||||
|
||||
---
|
||||
*State initialized: 2026-02-27*
|
||||
@@ -105,5 +107,5 @@ All decisions archived in PROJECT.md Key Decisions table and RETROSPECTIVE.md. K
|
||||
| 18 | add multi-column metadata display to playlist-details | 2026-03-08 | ce23177 | [18-add-multi-column-metadata-display-to-pla](./quick/18-add-multi-column-metadata-display-to-pla/) |
|
||||
| 19 | fix phantom playlist tracks with multi-root path resolution | 2026-03-16 | 9144ded | [19-fix-phantom-playlist-tracks](./quick/19-fix-phantom-playlist-tracks/) |
|
||||
|
||||
Last activity: 2026-03-19 - completed 20-01-PLAN.md
|
||||
*Last updated: 2026-03-19 — completed 20-01-PLAN.md (OGG Vorbis tag writer implementation)*
|
||||
Last activity: 2026-03-19 - completed 20-02-PLAN.md
|
||||
*Last updated: 2026-03-19 — completed 20-02-PLAN.md (OGG Vorbis tag writer tests)*
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
phase: 20-ogg-vorbis-tag-writer
|
||||
plan: 02
|
||||
subsystem: tagwriter
|
||||
tags: [ogg, vorbis, testing, round-trip, crc32, metadata, cover-art, dhowden-tag]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 20-ogg-vorbis-tag-writer
|
||||
provides: writeOggTags, parseOggPages, oggCRC, pipeline integration
|
||||
provides:
|
||||
- Comprehensive round-trip tests for OGG Vorbis tag writer (OGG-01 through OGG-06)
|
||||
- Programmatic OGG Vorbis test fixture builder
|
||||
- CRC32 validation against known vectors
|
||||
affects: [tagwriter]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns: [programmatic OGG Vorbis fixture generation, CRC32 known-vector validation]
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- backend/tagwriter/ogg_test.go
|
||||
modified: []
|
||||
|
||||
key-decisions:
|
||||
- "Programmatic OGG fixture builder instead of embedded binary — avoids fragile byte literals, uses Plan 01 page structures directly"
|
||||
- "CRC32 validated against independently computed known vectors (OggS→0x5fb0a94f, {1..8}→0x7d0f3681) plus fixture self-consistency"
|
||||
|
||||
patterns-established:
|
||||
- "OGG test fixture via createTestOGG: builds identification + comment + setup + audio pages programmatically"
|
||||
- "Audio preservation test: capture audio page data before/after write, assert byte-identical"
|
||||
|
||||
requirements-completed: [OGG-01, OGG-02, OGG-03, OGG-04, OGG-05, OGG-06]
|
||||
|
||||
# Metrics
|
||||
duration: 5min
|
||||
completed: 2026-03-19
|
||||
---
|
||||
|
||||
# Phase 20 Plan 02: OGG Vorbis Tag Writer Tests Summary
|
||||
|
||||
**9 round-trip test functions covering all 6 OGG requirements with programmatic fixture builder, CRC32 known-vector validation, and dhowden/tag read-back verification**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 5 min
|
||||
- **Started:** 2026-03-19T17:56:41Z
|
||||
- **Completed:** 2026-03-19T18:02:38Z
|
||||
- **Tasks:** 3
|
||||
- **Files modified:** 1
|
||||
|
||||
## Accomplishments
|
||||
- Programmatic OGG Vorbis test fixture builder (createTestOGG) that constructs valid files from page structures
|
||||
- CRC32 validation against known vectors and fixture page self-consistency
|
||||
- All 9 text fields round-trip correctly through writeOggTags → metadata.ExtractTags (OGG-01)
|
||||
- Cover art embed, replace, and clear via METADATA_BLOCK_PICTURE (OGG-04)
|
||||
- Non-edited fields survive partial updates (OGG-02)
|
||||
- Audio page data byte-identical after tag write (OGG-03)
|
||||
- Atomic safety: corrupt files untouched on failure (OGG-05)
|
||||
- Non-Vorbis and multi-stream OGG rejection tested
|
||||
- Full tagwriter suite (MP3 + FLAC + WAV + OGG) passes with zero regressions
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Create OGG test fixture and CRC32 validation** - `246a991` (test)
|
||||
2. **Task 2: Write round-trip tests for all OGG requirements** - `f13aa70` (test)
|
||||
3. **Task 3: Full test suite verification** - no commit (verification-only, all green)
|
||||
|
||||
## Files Created/Modified
|
||||
- `backend/tagwriter/ogg_test.go` - 659 lines: test fixture builder, CRC32 validation, 9 round-trip test functions covering all OGG requirements
|
||||
|
||||
## Decisions Made
|
||||
- Built OGG test fixture programmatically using Plan 01's page structures (buildVorbisIdentPacket, buildHeaderPages, writeOggPage) rather than embedding a pre-generated binary — gives full control and avoids fragile byte literals
|
||||
- CRC32 validated with independently computed known vectors plus self-consistency checks on fixture pages
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
None
|
||||
|
||||
## User Setup Required
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
- Phase 20 (OGG Vorbis tag writer) is complete — implementation + tests both done
|
||||
- All format writers now have comprehensive test coverage: MP3, FLAC, WAV, OGG
|
||||
- Ready for phase transition to next milestone phase
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
All files verified on disk, all commits found in git log. ogg_test.go is 659 lines (exceeds 300 minimum).
|
||||
|
||||
---
|
||||
*Phase: 20-ogg-vorbis-tag-writer*
|
||||
*Completed: 2026-03-19*
|
||||
Reference in New Issue
Block a user