# 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`.