1.5 KiB
Capability Spec: metadata
Package: @suaveplan/audio-metadata
Version: 0.0.0 (genesis)
Status: ADDED
ADDED Requirements
META-01 — Normalised Track
Track MUST be { title?, artist?, albumArtist?, album?, year?, genre?, trackNumber?, discNumber?, duration: number (seconds), bitrate?, sampleRate?, channels?, codec?, format: AudioFormat, coverArt?: Blob | Uint8Array }. All parsers MUST produce this shape and pass TrackSchema.parse.
META-02 — Runtime agnostic
MetadataExtractor MUST work in Node and browser. extractFromUrl MUST use fetch (global in browsers, Node ≥ 18). extractFromFile MUST read File / Blob via arrayBuffer(). No direct filesystem access in source code.
META-03 — Format support
The extractor MUST parse MP3 (ID3v1 + ID3v2.3/2.4), M4A/MP4 (iTunes ilst atoms), FLAC (Vorbis comments + METADATA_BLOCK_PICTURE), Ogg (Vorbis), WAV (RIFF LIST INFO), AIFF (ID3). Unknown containers MUST surface as METADATA.UNSUPPORTED_FORMAT.
META-04 — Streaming parse
extractFromUrl MUST use Range: bytes=… requests where the server signals accept-ranges: bytes to avoid downloading the full audio payload when options.coverArt === false.
META-05 — Observability
Every extract call MUST record metadata.extract.duration_ms histogram and metadata.extract.total{format, outcome} counter.
META-06 — Error reporting
Parser failures MUST surface as METADATA.PARSE_ERROR with { format, offset, reason } context. Network failures MUST surface as METADATA.FETCH_FAILED.