docs(20): capture phase context

2026-03-19 13:06:07 -04:00
parent 1f0fe2cc2e
commit 707d759ced
1 changed files with 71 additions and 0 deletions
@@ -0,0 +1,71 @@
+# Phase 20: OGG Vorbis Tag Writer - Context
+
+**Gathered:** 2026-03-19
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Extend the tag writing pipeline to write metadata and cover art to OGG Vorbis files via a custom OGG page rewriter. Users get the same edit experience as MP3/FLAC/WAV — single-track and batch editing both work. Full file rewrite (not in-place page editing). No OGG Opus, no multi-stream, no external tools.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Existing comment handling
+- Normalize all Vorbis Comment field names to uppercase on write (consistent with FLAC writer pattern)
+- Preserve duplicate field entries for non-edited fields as-is (multi-value fields are spec-legal); when editing a field, replace all entries with a single new value
+- Preserve the original vendor string — we're a tag editor, not an encoder
+- Preserve raw bytes for non-edited fields even if they contain invalid UTF-8 — don't break existing tags because another tool was sloppy
+
+### Cover art edge cases
+- When writing or removing cover art, also strip legacy COVERART and COVERARTMIME Vorbis Comment fields to prevent stale art from lingering
+- "Clear cover art" removes ALL picture-related fields: METADATA_BLOCK_PICTURE, COVERART, and COVERARTMIME
+- When setting cover art, replace all existing METADATA_BLOCK_PICTURE entries with a single front cover (same approach as FLAC writer)
+- Write path only — dhowden/tag already handles reading OGG cover art for display
+
+### Error behavior for malformed OGG
+- Lenient read, strict write — accept pages with bad CRC on read (some tools produce wrong CRCs), always write correct CRCs (matches WAV parser lenient-read/strict-write philosophy)
+- Reject truncated files — if we can't read the complete file structure, refuse the edit (can't guarantee audio preservation on a broken file)
+- Reject non-Vorbis OGG — only support OGG Vorbis (check for `\x01vorbis` magic in identification header); OGG Opus, Theora, FLAC, etc. get a clear error
+- User-friendly error messages with specific details ("Could not save tags to file.ogg: disk full"), technical info logged via slog
+
+### Multi-stream detection
+- Detect early during parse (fail fast), before any write work begins
+- Count unique serial numbers across pages — more than one means multi-stream
+- Reject chained streams too (multiple sequential Vorbis streams in one file) — unusual for music libraries, each has its own comment header
+- Clear rejection message: "This OGG file contains multiple streams and cannot be edited"
+
+### Claude's Discretion
+- OGG page size decisions (how to split large Vorbis Comment across pages)
+- CRC32 implementation details (MSB-first bit ordering per the OGG spec warning)
+- Page sequence number renumbering strategy when comment header page count changes
+- Exact structure of the custom OGG page parser/writer
+- Test file generation approach for round-trip tests
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- Follow the same lenient-read/strict-write philosophy as the WAV RIFF parser — be forgiving about what we accept, strict about what we produce
+- The pipeline integration is mechanical: add `FormatOGG` to `DetectFormat`, add `case FormatOGG: err = writeOggTags(...)` to the pipeline switch — same pattern as WAV
+- Reuse the existing `replaceVorbisComment` pattern from `flac.go` for text field manipulation (field name uppercase, filter-then-add)
+- OGG CRC32 uses non-standard MSB-first bit ordering — Go's `hash/crc32` produces wrong checksums (documented in STATE.md warnings)
+- OGG page sequence numbers must be renumbered when comment header page count changes (documented in STATE.md warnings)
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Migrate legacy COVERART field to METADATA_BLOCK_PICTURE (TAG-01 — tracked in REQUIREMENTS.md future requirements)
+- OGG Opus tag writing (FMT-01 — different header structure, `OpusTags` vs `\x03vorbis`, no framing bit)
+
+</deferred>
+
+---
+
+*Phase: 20-ogg-vorbis-tag-writer*
+*Context gathered: 2026-03-19*