Module metadata 

Publishing tags for MP3 (ID3v2.4), FLAC and WAV INFO.

Tags gives known fields one spelling across containers; the native AudioMetadata map remains available for custom fields and existing callers. EncodeOptions::tags and DecodeInfo::tags carry structured tags; whole decoding exposes them through Audio::info. Incremental stream::Decoder reads samples and does not expose tag tables.

MP3 and FLAC support every field and a JPEG/PNG front cover. WAV INFO supports title, artist, album, track, year, genre and comment. Unsupported structured fields/covers return EncodeError; they are never silently omitted. Native WAV keys remain four-character codes, and FLAC keys remain lowercase Vorbis names. MP3 native keys use the structured field names, with custom keys in TXXX frames.

Text is UTF-8 on writing; embedded NUL is rejected. Readers validate UTF-8 in new tag data (MP3 also reads Latin-1/UTF-16). Metadata is bounded before copying by MAX_METADATA_BYTES and MAX_METADATA_FIELDS, in addition to container limits. These bound encoded payloads, not allocator overhead or duplicate native and structured strings. Cover bytes are preserved without decoding the image; MIME/signature validation is not a full image integrity check. FLAC’s informational image dimensions are written as zero (unknown), as specified in RFC 9639 §8.8.

Structs

CoverArt

Caller-supplied JPEG/PNG bytes for a front cover. No image transcoding occurs.

Tags

Structured publishing fields. Track/disc text can be 1 or 1/12; year is recording-date text, normally 2026 (MP3 TDRC / FLAC DATE / WAV ICRD). Optional values are distinct from absent fields, including empty strings.

Constants

MAX_METADATA_BYTES

Maximum combined supported metadata payload, 16 MiB minus one byte.

MAX_METADATA_FIELDS

Maximum number of text fields/frames accepted in a tag table.