v0.6.0

What's New in v0.6.0

🧹 Breaking Changes for Better API Design

This release removes deprecated functionality and improves API consistency across the library.

Change	Rationale
Removed MusicIpId	MusicIP service discontinued; use AcoustID instead
Removed AiffFile.TryParse	Use AiffFile.Read which returns result type with error context
Removed WavFile.ReadFromData	Use WavFile.Read for span-based parsing
AudioProperties → struct	Better performance and immutability semantics
Renamed AsfFile.AudioProperties	Now Properties for consistency with other file types

📊 Quality Metrics

• Test coverage: 90.1% line, 77.6% branch
• Test count: 3,780 passing tests (+605 from v0.5.0)
• Formats: 15 audio formats with full read/write
• Build: Zero warnings, all analyzers passing

💡 Migration Notes

MusicIpId Removal

// Before (v0.5.0)
tag.MusicIpId = "..."

// After (v0.6.0) - Use AcoustID instead
tag.AcoustId = "..."

AudioProperties Struct

// Before (v0.5.0)
AudioProperties props = file.Properties; // class

// After (v0.6.0)
AudioProperties props = file.Properties; // readonly struct (no API changes needed)

ASF Properties

// Before (v0.5.0)
var props = asfFile.AudioProperties;

// After (v0.6.0)
var props = asfFile.Properties; // Consistent with other formats

📦 Installation

dotnet add package TagLibSharp2 --version 0.6.0

🔗 Links

• Full Changelog
• Migration Guide from TagLib#
• Cookbook

---

Full Changelog: v0.5.0...v0.6.0

v0.5.0

What's New in v0.5.0

🎵 New Format Support (5 formats)

Format	Description
ASF/WMA	Windows Media Audio with full metadata support
Musepack	SV7 and SV8 streams with APE tags
WavPack	Lossless compression with APE tags
Monkey's Audio	APE format (old and new headers)
Ogg FLAC	FLAC in Ogg container with Vorbis Comments

🔊 DSD Enhancements

• DSF write support - Save metadata to DSD Stream Files
• DFF write support - Save metadata to DSDIFF files
• Full DSD64/128/256/512 sample rate detection

🏷️ APE Tag v2 Infrastructure

• Complete APE v2 tag implementation
• Text, Binary, and External item types
• Read-only flag support
• Used by WavPack, Musepack, and Monkey's Audio

📊 Quality Metrics

• Test coverage: 90.1% line, 77.6% branch
• Test count: 3,248 passing tests (+903 from v0.4.0)
• Formats: 15 audio formats with full read/write
• Build: Zero warnings, all analyzers passing

📦 Installation

dotnet add package TagLibSharp2 --version 0.5.0

🔗 Links

• Full Changelog
• Migration Guide from TagLib#
• Cookbook

---

Full Changelog: v0.4.0...v0.5.0

v0.4.0 - MP4/M4A Support

MP4/M4A Format Support

This release adds full read/write support for MP4/M4A audio files (AAC, ALAC) with iTunes-style metadata.

Highlights

• Full MP4/M4A support - ISO 14496-12/14 compliant box parsing
• iTunes metadata - All standard atoms (©nam, ©ART, ©alb, trkn, disk, covr, etc.)
• Audio properties - Duration, sample rate, bitrate, channels, codec detection
• Album art - JPEG/PNG cover art via covr atom
• MusicBrainz IDs - Full support via freeform atoms
• ReplayGain/R128 - Track and album gain values
• MediaFile factory - Auto-detection of MP4 format
• Atomic writes - Safe file saving with mdat relocation

Audio Codec Support

• AAC (via esds parsing)
• ALAC (via magic cookie parsing)
• Detection for FLAC, Opus, AC-3, E-AC-3 in MP4 container

Metadata Atoms

Category	Atoms
Basic	Title, Artist, Album, Genre, Year, Comment, Composer
Album	Album Artist, Track/Disc Numbers, Compilation, Gapless
Sort	AlbumSort, ArtistSort, TitleSort, ComposerSort
Classical	Work, Movement Name/Number/Count, Show Movement
Freeform	MusicBrainz IDs, AcoustID, ReplayGain, R128, ISRC

Statistics

• 197 new MP4 tests
• 2,318 total tests passing
• 88.67% code coverage

See CHANGELOG.md for full details.

v0.3.0 - Ogg Opus Support & Security Hardening

What's New

Added

Ogg Opus Format Support

• OggOpusFile class for reading and writing Opus audio files
• OpusHead identification header parsing (RFC 7845)
  • Version, channels, pre-skip, input sample rate, output gain
  • Channel mapping family support
• OpusTags (Vorbis Comment) metadata support (no framing bit, per RFC 7845)
• Full read/write round-trip support with atomic file saves

Audio Properties for Opus

• AudioProperties.FromOpus() factory method
• Duration calculation from granule position (always 48kHz output)
• Pre-skip compensation for accurate duration

MediaFile Factory Updates

• MediaFormat.Opus enum value
• Automatic Opus vs Vorbis detection by inspecting first Ogg packet
• .opus file extension support

R128 Loudness Convenience Properties

• R128TrackGainDb and R128AlbumGainDb properties on Tag base class
• Convert Q7.8 fixed-point integers to/from decibels as doubles

Fixed

RFC 3533 Compliance (Ogg Container)

• Add segment table overflow validation in OggPageHelper.BuildOggPage
• Add bounds check in FindLastGranulePosition for truncated pages
• Add BuildMultiPagePacket helper for large metadata spanning multiple pages

RFC 7845 Compliance (Opus Codec)

• Add channel mapping family 1 validation (1-8 channels per §5.1.1.2)
• Existing OpusHead minimum size validation (19 bytes) now tested

R128 Gain Handling

• Fix integer overflow in R128TrackGainDb and R128AlbumGainDb setters for extreme values
• Add ClampToQ78 helper to safely clamp dB values to Q7.8 format range

Vorbis Validation

• Add validation for invalid vorbis_version in identification header (must be 0 per spec)
• Return explicit error for Vorbis files with zero sample rate or channel count

Security Hardening

• Add 16 MB max packet size limit in OggPageHelper.ExtractHeaderPackets to prevent DoS
• Add stream/coupled count validation for Opus mapping families 1 & 255

Changed

• Refactor: OggVorbisFile now uses shared OggPageHelper code (eliminates ~160 lines of duplicate code)
• Test count increased from 1939 to 2077 (+138 tests)
• Code coverage: 89.4% line / 75.8% branch

---

Full Changelog: https://github.com/decriptor/tagsharp/blob/main/CHANGELOG.md

v0.2.1

What's Changed

Added

Error Context for File Parsing

• WavFileReadResult struct with IsSuccess, File, and Error properties
• AiffFileReadResult struct with IsSuccess, File, and Error properties
• WavFile.Read(ReadOnlySpan<byte>) returns result type with error context
• AiffFile.Read(ReadOnlySpan<byte>) returns result type with error context
• AiffFile.ReadFromFile and ReadFromFileAsync methods for direct file loading

Test Coverage

• PolyfillsTests.cs - Hex conversion and Latin1 encoding tests
• OggCrcTests.cs - CRC-32 calculation and validation tests
• Id3v1GenreTests.cs - Genre lookup for all 192 genres
• DocExamplesCompileTests.cs - Verify documentation code examples compile
• ResultTypeEqualityTests.cs - IEquatable tests for 27 result types
• StructEqualityTests.cs - Equality tests for SyncLyricsItem, FlacPreservedBlock, etc.
• AiffFileTests.cs - ReadFromFile and ReadFromFileAsync coverage

Documentation

• Fix Cookbook.md: Correct SyncLyricsFrame API (SyncLyricsItem, SyncLyricsType)
• Fix Cookbook.md: Correct ChapterFrame API (StartTimeMs, EndTimeMs)

Changed

• WavFile.ReadFromFile and ReadFromFileAsync now return WavFileReadResult
• AiffFile.ReadFromFile and ReadFromFileAsync now return AiffFileReadResult
• Test count increased from 1756 to 1939 (+183 tests)

Full Changelog: v0.2.0...v0.2.1

v0.2.0

What's New in v0.2.0

This release significantly expands format support and adds critical features for professional audio workflows.

🎵 ID3v2.2 Legacy Support

• Full ID3v2.2 (3-character frame ID) parsing support
• Complete v2.2 → v2.3/v2.4 frame ID mapping (66 mappings)
• Proper 3-byte big-endian size handling for v2.2 frames

🔄 ID3v2 Unsynchronization

• Global unsynchronization support (tag-level, v2.3/v2.4)
• Per-frame unsynchronization support (v2.4 frame flag)
• Proper 0xFF 0x00 byte sequence removal during parsing

🏷️ ID3v2 Frame Flags Processing

• Compression support with zlib decompression (v2.3 and v2.4)
• Grouping identity flag handling
• Data length indicator parsing (v2.4 syncsafe 4-byte prefix)
• Encryption flag detection

🔐 FLAC MD5 Audio Signature

• FlacFile.AudioMd5Signature property for 128-bit MD5 hash of unencoded audio
• FlacFile.AudioMd5SignatureHex for hex string representation
• Essential for bit-perfect archive verification

🖼️ Picture Support for WAV and AIFF

• WavFile.Pictures and AiffFile.Pictures via embedded ID3v2 tag
• CoverArt convenience property for primary album art
• Full PictureType support (FrontCover, BackCover, etc.)

💾 SaveToFile Convenience Overloads

• SaveToFile(path) on Mp3File, FlacFile, OggVorbisFile, WavFile, AiffFile
• All with async variants accepting CancellationToken

✍️ AIFF Write Support

• AiffFile.Render for serializing AIFF files to binary data
• AiffFile.SaveToFile and SaveToFileAsync for atomic file saves
• Settable Tag property for modifying ID3v2 metadata

📦 Metadata Preservation

• FLAC: Preserve SEEKTABLE and APPLICATION blocks during render
• WAV: Preserve all unknown chunks (fact, cue, smpl, etc.) during render

🎚️ AIFC Compression Support

• AiffAudioProperties.CompressionType for AIFC compression type
• AiffAudioProperties.CompressionName for human-readable description

📻 BWF (Broadcast Wave Format) Support

• BextTag class for parsing and writing bext chunks
• Description, Originator, OriginatorReference fields
• TimeReference for sample-accurate synchronization
• UMID for Version 1+ and CodingHistory tracking

🔊 WAVEFORMATEXTENSIBLE Support

• Extended fmt chunk parsing for professional audio
• ValidBitsPerSample, ChannelMask, SubFormat properties
• 5.1, 7.1 surround sound speaker position support

✅ Ogg CRC Validation

• Optional validateCrc parameter on OggVorbisFile read methods
• Useful for detecting file corruption in critical applications

🛡️ Security

• Integer overflow protection for malformed chunk sizes
• Defense-in-depth checks in AIFF, RIFF, and WAV parsers

📊 Quality

• Test count increased from 1528 to 1658 (+130 tests)

---

Full Changelog: v0.1.0...v0.2.0

v0.1.0

TagLibSharp2 v0.1.0

First public release of TagLibSharp2 - a clean-room MIT-licensed audio metadata library for .NET.

Highlights

• MIT License - No GPL/LGPL restrictions
• Modern .NET - Async/await, Span, nullable annotations
• Format Support - ID3v1, ID3v2.3/v2.4, FLAC, Ogg Vorbis
• Extended Metadata - ReplayGain, MusicBrainz, R128, AcoustID

Supported Formats

Format	Read	Write
MP3 (ID3v1/v2)	✅	✅
FLAC	✅	✅
Ogg Vorbis	✅	✅

Installation

dotnet add package TagLibSharp2 --version 0.1.0

See CHANGELOG.md for full details.