suaveplan/openspec/archive/2026-04-19-enterprise-metadata/proposal.md

OpenSpec Change: enterprise-metadata

• Change ID: enterprise-metadata
• Package: @suaveplan/audio-metadata
• Category: universal
• Target path: universal/data/metadata
• Status: PROPOSED
• Date: 2026-04-19
• Reference spec: /mnt/s/web/suaveplan/enterprise/metadata.md

Summary

Greenfield rebuild of @suaveplan/audio-metadata — a universal audio-and-media metadata extractor that works in both Node and browser. Parses ID3v1/v2, MP4/M4A atoms, FLAC Vorbis comments, Ogg, WAV, AIFF, and returns a normalised Track record (title/artist/album/cover/duration/bitrate). Supplies the data layer used by players and libraries.

Current-state audit (genesis)

Package does not exist yet — fresh build.

Dependencies

• Workspace: none (leaf)
• External (via catalog): zod, tslib, @opentelemetry/api
• Dev (via catalog): vitest, @vitest/coverage-istanbul, fast-check, mitata

Preserved public surface

• MetadataExtractor (singleton .getInstance()) with methods:
  • extractFromUrl(url, options?): Promise<Track>
  • extractFromBuffer(buffer, options?): Promise<Track>
  • extractFromFile(file: File|Blob, options?): Promise<Track> (browser)
• Types: Track, AudioMetadata, MetadataExtractionOptions

New genesis additions

• Codes: METADATA.UNSUPPORTED_FORMAT, METADATA.PARSE_ERROR, METADATA.FETCH_FAILED.
• Zod schemas for Track, AudioMetadata.
• OTel histogram metadata.extract.duration_ms{format}; counter metadata.extract.total{format, outcome}.
• Differential tests against music-metadata on fixtures (parity without pulling the dependency into production runtime).

Impact

• Adds one new package: universal/data/metadata
• Adds one new spec capability: metadata